Bands

Band

A data band in images of a specific product.

SpectralBand

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

MicrowaveBand

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

MaskBand

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

ClassBand

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

GenericBand

A generic kind of band not fitting any other type.

DerivedBand

A band with pixel values computed from the data in other bands.


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.

Common attributes: id, name, product_id, description, type, sort_order, data_type, no_data, data_range, display_range, resolution, band_index, file_index, jpx_layer_index.

To create a new band instantiate one of those specialized classes:

Methods

delete(id[, client])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

search([client])

A search query for all bands.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

Replace any sequence of invalid characters in a string with a single _ character to create a valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

Note that it is possible that two unique invalid names may turn into duplicate valid names if the uniqueness is located in the same sequence of invalid characters.

Parameters

name (str) – A name for a Band or Image that may contain invalid characters.

Returns

A name for a Band or Image that does not contain any invalid characters.

Return type

str

Example

>>> name = "This is ań @#$^*% ïñvalid name!!!!"
>>> band = SpectralBand()
>>> band.name = Band.make_valid_name(name)
>>> band.name
'This_is_a_valid_name_'
>>>
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.

Instantiating a spectral band indicates that you want to create a new Descartes Labs catalog spectral band. If you instead want to retrieve an existing catalog spectral band use Band.get(), or if you’re not sure use SpectralBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

band_index

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

created

The point in time this object was created.

data_range

The range of pixel values stored in the band.

data_type

The data type for pixel values in this band.

description

A description with further details on the band.

display_range

The range of pixel values for display purposes.

extra_properties

A dictionary of up to 50 key/value pairs.

file_index

The 0-based index into the list of source files.

id

An optional unique identifier for this object.

is_modified

Whether any attributes were changed (see state).

jpx_layer_index

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

modified

The point in time this object was last modified.

name

The name of the catalog object.

nodata

A value representing missing data in a pixel in this band.

owners

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

product

The product instance this catalog object belongs to.

product_id

The id of the product this catalog object belongs to.

readers

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

resolution

The spatial resolution of this band.

sort_order

A number defining the default sort order for bands within a product.

state

The state of this catalog object.

tags

A list of up to 20 tags.

type

The type of this band, directly corresponding to a Band derived class.

wavelength_nm_center

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

wavelength_nm_fwhm

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

wavelength_nm_max

Maximum wavelength this band is sensitive to, in nm.

wavelength_nm_min

Minimum wavelength this band is sensitive to, in nm.

writers

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

Methods

delete(id[, client])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

reload()

Reload all attributes from the Descartes Labs catalog.

save([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client])

A search query for all bands.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

classmethod make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

Replace any sequence of invalid characters in a string with a single _ character to create a valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

Note that it is possible that two unique invalid names may turn into duplicate valid names if the uniqueness is located in the same sequence of invalid characters.

Parameters

name (str) – A name for a Band or Image that may contain invalid characters.

Returns

A name for a Band or Image that does not contain any invalid characters.

Return type

str

Example

>>> name = "This is ań @#$^*% ïñvalid name!!!!"
>>> band = SpectralBand()
>>> band.name = Band.make_valid_name(name)
>>> band.name
'This_is_a_valid_name_'
>>>
reload()

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save(extra_attributes=None)

Saves this object to the Descartes Labs catalog.

If this instance was created using the constructor, it will be in the UNSAVED state and is considered a new Descartes Labs catalog object that must be created. If the catalog object already exists in this case, this method will raise a BadRequestError.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and any of its values were changed, it will be in the MODIFIED state and the existing catalog object will be updated.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no extra_attributes parameter is given, nothing will happen.

Parameters

extra_attributes (dict, optional) – A dictionary of attributes that should be sent to the catalog along with attributes already set on this object. Empty by default. If not empty, and the object is in the SAVED state, it is updated in the Descartes Labs catalog even though no attributes were modified.

Raises

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.state
<DocumentState.UNSAVED: 'unsaved'>
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
my_org_id:my-product
>>> # Now you can retrieve the product and update it
>>> existing_product = Product.get(new_product.id)
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> existing_product.name = "My Updated Product"
>>> existing_product.state
<DocumentState.MODIFIED: 'modified'>
>>> existing_product.save()
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> # After you delete it...
>>> existing_product.delete()
True
>>> product.state
<DocumentState.DELETED: 'deleted'>
classmethod search(client=None)

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

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters

ignore_errors (bool, optional) – False by default. When set to True, it will suppress AttributeValidationError and AttributeError. Any given attribute that causes one of these two exceptions will be ignored, all other attributes will be set to the given values.

Raises
  • AttributeValidationError – If one or more of the attributes being updated are immutable.

  • AttributeError – If one or more of the attributes are not part of this catalog object.

  • DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('wavelength_nm_center', 'wavelength_nm_min', 'wavelength_nm_max', 'wavelength_nm_fwhm', 'description', 'type', 'sort_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'id', 'name', 'product_id', 'product', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'created', 'modified')
band_index

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

Type

int

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

data_range

The range of pixel values stored in the band.

The two floats are the minimum and maximum pixel values stored in this band.

Type

tuple(float, float)

data_type

The data type for pixel values in this band.

Type

str or DataType

description

A description with further details on the band.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, optional

display_range

The range of pixel values for display purposes.

The two floats are the minimum and maximum values indicating a default reasonable range of pixel values usd when rastering this band for display purposes.

Type

tuple(float, float)

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary 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

file_index

The 0-based index into the list of source files.

If there are multiple files, it maps the band index to the file index. It defaults to 0 (first file).

Type

int, optional

id

An optional unique identifier for this object.

The identifier for a named catalog object is the concatenation of the product_id and name, separated by a colon. It will be generated from the product_id and the name if not provided. Otherwise, the name and product_id are extracted from the id. A AttributeValidationError will be raised if it conflicts with an existing product_id and/or name.

Type

str, immutable

property is_modified

Whether any attributes were changed (see state).

True if any of the attribute values changed since the last time this catalog object was retrieved or saved. False otherwise.

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

Type

bool

jpx_layer_index

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

Defaults to 0.

Type

int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of the catalog object.

The name of a named catalog object is unique within a product and object type (images and bands). The name can contain alphanumeric characters, -, _, and . up to 2000 characters. If the id contains a name, it will be used instead. Once set, it cannot be changed.

Sortable.

Type

str, immutable

nodata

A value representing missing data in a pixel in this band.

Type

float, optional

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

product

The product instance this catalog object belongs to.

If given, it is used to retrieve the product_id.

Filterable.

Type

Product, immutable

product_id

The id of the product this catalog object belongs to.

If the id contains a product id, it will be used instead. Once set, it cannot be changed.

Filterable, sortable.

Type

str, immutable

readers

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

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

Type

list(str), optional

resolution

The spatial resolution of this band.

Filterable, sortable.

Type

Resolution, optional

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, optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

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

Filterable.

Type

list, optional

type

The type of this band, directly corresponding to a Band derived class.

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class 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 or BandType

wavelength_nm_center

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

Filterable, sortable.

Type

float, optional

wavelength_nm_fwhm

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

Filterable, sortable.

Type

float, optional

wavelength_nm_max

Maximum wavelength this band is sensitive to, in nm.

Filterable, sortable.

Type

float, optional

wavelength_nm_min

Minimum wavelength this band is sensitive to, in nm.

Filterable, sortable.

Type

float, 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 to the owners of a catalog object. See this note.

Type

list(str), optional

class MicrowaveBand(**kwargs)[source]

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

Instantiating a microwave band indicates that you want to create a new Descartes Labs catalog microwave band. If you instead want to retrieve an existing catalog microwave band use Band.get(), or if you’re not sure use MicrowaveBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

band_index

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

bandwidth

Chirp bandwidth of the sensor in MHz.

created

The point in time this object was created.

data_range

The range of pixel values stored in the band.

data_type

The data type for pixel values in this band.

description

A description with further details on the band.

display_range

The range of pixel values for display purposes.

extra_properties

A dictionary of up to 50 key/value pairs.

file_index

The 0-based index into the list of source files.

frequency

Center frequency of the observed microwave in GHz.

id

An optional unique identifier for this object.

is_modified

Whether any attributes were changed (see state).

jpx_layer_index

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

modified

The point in time this object was last modified.

name

The name of the catalog object.

nodata

A value representing missing data in a pixel in this band.

owners

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

product

The product instance this catalog object belongs to.

product_id

The id of the product this catalog object belongs to.

readers

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

resolution

The spatial resolution of this band.

sort_order

A number defining the default sort order for bands within a product.

state

The state of this catalog object.

tags

A list of up to 20 tags.

type

The type of this band, directly corresponding to a Band derived class.

writers

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

Methods

delete(id[, client])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

reload()

Reload all attributes from the Descartes Labs catalog.

save([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client])

A search query for all bands.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

classmethod make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

Replace any sequence of invalid characters in a string with a single _ character to create a valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

Note that it is possible that two unique invalid names may turn into duplicate valid names if the uniqueness is located in the same sequence of invalid characters.

Parameters

name (str) – A name for a Band or Image that may contain invalid characters.

Returns

A name for a Band or Image that does not contain any invalid characters.

Return type

str

Example

>>> name = "This is ań @#$^*% ïñvalid name!!!!"
>>> band = SpectralBand()
>>> band.name = Band.make_valid_name(name)
>>> band.name
'This_is_a_valid_name_'
>>>
reload()

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save(extra_attributes=None)

Saves this object to the Descartes Labs catalog.

If this instance was created using the constructor, it will be in the UNSAVED state and is considered a new Descartes Labs catalog object that must be created. If the catalog object already exists in this case, this method will raise a BadRequestError.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and any of its values were changed, it will be in the MODIFIED state and the existing catalog object will be updated.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no extra_attributes parameter is given, nothing will happen.

Parameters

extra_attributes (dict, optional) – A dictionary of attributes that should be sent to the catalog along with attributes already set on this object. Empty by default. If not empty, and the object is in the SAVED state, it is updated in the Descartes Labs catalog even though no attributes were modified.

Raises

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.state
<DocumentState.UNSAVED: 'unsaved'>
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
my_org_id:my-product
>>> # Now you can retrieve the product and update it
>>> existing_product = Product.get(new_product.id)
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> existing_product.name = "My Updated Product"
>>> existing_product.state
<DocumentState.MODIFIED: 'modified'>
>>> existing_product.save()
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> # After you delete it...
>>> existing_product.delete()
True
>>> product.state
<DocumentState.DELETED: 'deleted'>
classmethod search(client=None)

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

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters

ignore_errors (bool, optional) – False by default. When set to True, it will suppress AttributeValidationError and AttributeError. Any given attribute that causes one of these two exceptions will be ignored, all other attributes will be set to the given values.

Raises
  • AttributeValidationError – If one or more of the attributes being updated are immutable.

  • AttributeError – If one or more of the attributes are not part of this catalog object.

  • DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('frequency', 'bandwidth', 'description', 'type', 'sort_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'id', 'name', 'product_id', 'product', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'created', 'modified')
band_index

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

Type

int

bandwidth

Chirp bandwidth of the sensor in MHz.

Filterable, sortable.

Type

float, optional

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

data_range

The range of pixel values stored in the band.

The two floats are the minimum and maximum pixel values stored in this band.

Type

tuple(float, float)

data_type

The data type for pixel values in this band.

Type

str or DataType

description

A description with further details on the band.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, optional

display_range

The range of pixel values for display purposes.

The two floats are the minimum and maximum values indicating a default reasonable range of pixel values usd when rastering this band for display purposes.

Type

tuple(float, float)

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary 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

file_index

The 0-based index into the list of source files.

If there are multiple files, it maps the band index to the file index. It defaults to 0 (first file).

Type

int, optional

frequency

Center frequency of the observed microwave in GHz.

Filterable, sortable.

Type

float, optional

id

An optional unique identifier for this object.

The identifier for a named catalog object is the concatenation of the product_id and name, separated by a colon. It will be generated from the product_id and the name if not provided. Otherwise, the name and product_id are extracted from the id. A AttributeValidationError will be raised if it conflicts with an existing product_id and/or name.

Type

str, immutable

property is_modified

Whether any attributes were changed (see state).

True if any of the attribute values changed since the last time this catalog object was retrieved or saved. False otherwise.

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

Type

bool

jpx_layer_index

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

Defaults to 0.

Type

int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of the catalog object.

The name of a named catalog object is unique within a product and object type (images and bands). The name can contain alphanumeric characters, -, _, and . up to 2000 characters. If the id contains a name, it will be used instead. Once set, it cannot be changed.

Sortable.

Type

str, immutable

nodata

A value representing missing data in a pixel in this band.

Type

float, optional

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

product

The product instance this catalog object belongs to.

If given, it is used to retrieve the product_id.

Filterable.

Type

Product, immutable

product_id

The id of the product this catalog object belongs to.

If the id contains a product id, it will be used instead. Once set, it cannot be changed.

Filterable, sortable.

Type

str, immutable

readers

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

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

Type

list(str), optional

resolution

The spatial resolution of this band.

Filterable, sortable.

Type

Resolution, optional

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, optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

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

Filterable.

Type

list, optional

type

The type of this band, directly corresponding to a Band derived class.

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class 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 or BandType

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 to the owners of a catalog object. See this note.

Type

list(str), optional

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).

Instantiating a mask band indicates that you want to create a new Descartes Labs catalog mask band. If you instead want to retrieve an existing catalog mask band use Band.get(), or if you’re not sure use MaskBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

band_index

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

created

The point in time this object was created.

data_range

[0, 1].

data_type

The data type for pixel values in this band.

description

A description with further details on the band.

display_range

[0, 1].

extra_properties

A dictionary of up to 50 key/value pairs.

file_index

The 0-based index into the list of source files.

id

An optional unique identifier for this object.

is_alpha

Whether this band should be useable as an alpha band during rastering.

is_modified

Whether any attributes were changed (see state).

jpx_layer_index

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

modified

The point in time this object was last modified.

name

The name of the catalog object.

nodata

A value representing missing data in a pixel in this band.

owners

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

product

The product instance this catalog object belongs to.

product_id

The id of the product this catalog object belongs to.

readers

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

resolution

The spatial resolution of this band.

sort_order

A number defining the default sort order for bands within a product.

state

The state of this catalog object.

tags

A list of up to 20 tags.

type

The type of this band, directly corresponding to a Band derived class.

writers

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

Methods

delete(id[, client])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

reload()

Reload all attributes from the Descartes Labs catalog.

save([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client])

A search query for all bands.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

classmethod make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

Replace any sequence of invalid characters in a string with a single _ character to create a valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

Note that it is possible that two unique invalid names may turn into duplicate valid names if the uniqueness is located in the same sequence of invalid characters.

Parameters

name (str) – A name for a Band or Image that may contain invalid characters.

Returns

A name for a Band or Image that does not contain any invalid characters.

Return type

str

Example

>>> name = "This is ań @#$^*% ïñvalid name!!!!"
>>> band = SpectralBand()
>>> band.name = Band.make_valid_name(name)
>>> band.name
'This_is_a_valid_name_'
>>>
reload()

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save(extra_attributes=None)

Saves this object to the Descartes Labs catalog.

If this instance was created using the constructor, it will be in the UNSAVED state and is considered a new Descartes Labs catalog object that must be created. If the catalog object already exists in this case, this method will raise a BadRequestError.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and any of its values were changed, it will be in the MODIFIED state and the existing catalog object will be updated.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no extra_attributes parameter is given, nothing will happen.

Parameters

extra_attributes (dict, optional) – A dictionary of attributes that should be sent to the catalog along with attributes already set on this object. Empty by default. If not empty, and the object is in the SAVED state, it is updated in the Descartes Labs catalog even though no attributes were modified.

Raises

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.state
<DocumentState.UNSAVED: 'unsaved'>
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
my_org_id:my-product
>>> # Now you can retrieve the product and update it
>>> existing_product = Product.get(new_product.id)
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> existing_product.name = "My Updated Product"
>>> existing_product.state
<DocumentState.MODIFIED: 'modified'>
>>> existing_product.save()
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> # After you delete it...
>>> existing_product.delete()
True
>>> product.state
<DocumentState.DELETED: 'deleted'>
classmethod search(client=None)

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

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters

ignore_errors (bool, optional) – False by default. When set to True, it will suppress AttributeValidationError and AttributeError. Any given attribute that causes one of these two exceptions will be ignored, all other attributes will be set to the given values.

Raises
  • AttributeValidationError – If one or more of the attributes being updated are immutable.

  • AttributeError – If one or more of the attributes are not part of this catalog object.

  • DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('is_alpha', 'data_range', 'display_range', 'description', 'type', 'sort_order', 'data_type', 'nodata', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'id', 'name', 'product_id', 'product', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'created', 'modified')
band_index

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

Type

int

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

data_range

[0, 1].

Type

tuple(float, float), readonly

data_type

The data type for pixel values in this band.

Type

str or DataType

description

A description with further details on the band.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, optional

display_range

[0, 1].

Type

tuple(float, float), readonly

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary 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

file_index

The 0-based index into the list of source files.

If there are multiple files, it maps the band index to the file index. It defaults to 0 (first file).

Type

int, optional

id

An optional unique identifier for this object.

The identifier for a named catalog object is the concatenation of the product_id and name, separated by a colon. It will be generated from the product_id and the name if not provided. Otherwise, the name and product_id are extracted from the id. A AttributeValidationError will be raised if it conflicts with an existing product_id and/or name.

Type

str, immutable

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, optional

property is_modified

Whether any attributes were changed (see state).

True if any of the attribute values changed since the last time this catalog object was retrieved or saved. False otherwise.

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

Type

bool

jpx_layer_index

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

Defaults to 0.

Type

int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of the catalog object.

The name of a named catalog object is unique within a product and object type (images and bands). The name can contain alphanumeric characters, -, _, and . up to 2000 characters. If the id contains a name, it will be used instead. Once set, it cannot be changed.

Sortable.

Type

str, immutable

nodata

A value representing missing data in a pixel in this band.

Type

float, optional

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

product

The product instance this catalog object belongs to.

If given, it is used to retrieve the product_id.

Filterable.

Type

Product, immutable

product_id

The id of the product this catalog object belongs to.

If the id contains a product id, it will be used instead. Once set, it cannot be changed.

Filterable, sortable.

Type

str, immutable

readers

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

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

Type

list(str), optional

resolution

The spatial resolution of this band.

Filterable, sortable.

Type

Resolution, optional

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, optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

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

Filterable.

Type

list, optional

type

The type of this band, directly corresponding to a Band derived class.

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class 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 or BandType

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 to the owners of a catalog object. See this note.

Type

list(str), optional

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.

Instantiating a class band indicates that you want to create a new Descartes Labs catalog class band. If you instead want to retrieve an existing catalog class band use Band.get(), or if you’re not sure use ClassBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

band_index

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

class_labels

A list of labels.

colormap

A description of an attribute as received from the Descartes Labs catalog or set by the end-user.

colormap_name

Name of a predefined colormap for display purposes.

created

The point in time this object was created.

data_range

The range of pixel values stored in the band.

data_type

The data type for pixel values in this band.

description

A description with further details on the band.

display_range

The range of pixel values for display purposes.

extra_properties

A dictionary of up to 50 key/value pairs.

file_index

The 0-based index into the list of source files.

id

An optional unique identifier for this object.

is_modified

Whether any attributes were changed (see state).

jpx_layer_index

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

modified

The point in time this object was last modified.

name

The name of the catalog object.

nodata

A value representing missing data in a pixel in this band.

owners

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

product

The product instance this catalog object belongs to.

product_id

The id of the product this catalog object belongs to.

readers

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

resolution

The spatial resolution of this band.

sort_order

A number defining the default sort order for bands within a product.

state

The state of this catalog object.

tags

A list of up to 20 tags.

type

The type of this band, directly corresponding to a Band derived class.

writers

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

Methods

delete(id[, client])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

reload()

Reload all attributes from the Descartes Labs catalog.

save([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client])

A search query for all bands.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

classmethod make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

Replace any sequence of invalid characters in a string with a single _ character to create a valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

Note that it is possible that two unique invalid names may turn into duplicate valid names if the uniqueness is located in the same sequence of invalid characters.

Parameters

name (str) – A name for a Band or Image that may contain invalid characters.

Returns

A name for a Band or Image that does not contain any invalid characters.

Return type

str

Example

>>> name = "This is ań @#$^*% ïñvalid name!!!!"
>>> band = SpectralBand()
>>> band.name = Band.make_valid_name(name)
>>> band.name
'This_is_a_valid_name_'
>>>
reload()

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save(extra_attributes=None)

Saves this object to the Descartes Labs catalog.

If this instance was created using the constructor, it will be in the UNSAVED state and is considered a new Descartes Labs catalog object that must be created. If the catalog object already exists in this case, this method will raise a BadRequestError.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and any of its values were changed, it will be in the MODIFIED state and the existing catalog object will be updated.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no extra_attributes parameter is given, nothing will happen.

Parameters

extra_attributes (dict, optional) – A dictionary of attributes that should be sent to the catalog along with attributes already set on this object. Empty by default. If not empty, and the object is in the SAVED state, it is updated in the Descartes Labs catalog even though no attributes were modified.

Raises

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.state
<DocumentState.UNSAVED: 'unsaved'>
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
my_org_id:my-product
>>> # Now you can retrieve the product and update it
>>> existing_product = Product.get(new_product.id)
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> existing_product.name = "My Updated Product"
>>> existing_product.state
<DocumentState.MODIFIED: 'modified'>
>>> existing_product.save()
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> # After you delete it...
>>> existing_product.delete()
True
>>> product.state
<DocumentState.DELETED: 'deleted'>
classmethod search(client=None)

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

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters

ignore_errors (bool, optional) – False by default. When set to True, it will suppress AttributeValidationError and AttributeError. Any given attribute that causes one of these two exceptions will be ignored, all other attributes will be set to the given values.

Raises
  • AttributeValidationError – If one or more of the attributes being updated are immutable.

  • AttributeError – If one or more of the attributes are not part of this catalog object.

  • DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('colormap_name', 'colormap', 'class_labels', 'description', 'type', 'sort_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'id', 'name', 'product_id', 'product', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'created', 'modified')
band_index

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

Type

int

class_labels

A list of 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), optional

colormap

A description of an attribute as received from the Descartes Labs catalog or set by the end-user.

Changing the value of an attribute will set the corresponding CatalogObject to modified.

Parameters
  • mutable (bool) – Whether this attribute can be changed. Set to True by default. If set to False, the attribute can be set once and after that can only be set with the same value. If set with a different value, an AttributeValidationError will be raised.

  • serializable (bool) – Whether this attribute will be included during serialization. Set to True by default. If set to False, the attribute will be skipped during serialization.

  • sticky (bool) – Whether this attribute will be cleared when new attribute values are loaded from the Descartes Labs catalog. Set to False by default. This is used specifically for attributes that are only deserialised on the Descartes Labs catalog (load_only). These attributes will never appear in the data from the Descartes Labs catalog, and to allow them to persist you can set the _sticky parameter to True.

  • readonly (bool) – Whether this attribute can be set. Set to False by default. If set to True, the attribute can never be set and will raise an AttributeValidationError it set.

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 or Colormap, optional

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

data_range

The range of pixel values stored in the band.

The two floats are the minimum and maximum pixel values stored in this band.

Type

tuple(float, float)

data_type

The data type for pixel values in this band.

Type

str or DataType

description

A description with further details on the band.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, optional

display_range

The range of pixel values for display purposes.

The two floats are the minimum and maximum values indicating a default reasonable range of pixel values usd when rastering this band for display purposes.

Type

tuple(float, float)

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary 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

file_index

The 0-based index into the list of source files.

If there are multiple files, it maps the band index to the file index. It defaults to 0 (first file).

Type

int, optional

id

An optional unique identifier for this object.

The identifier for a named catalog object is the concatenation of the product_id and name, separated by a colon. It will be generated from the product_id and the name if not provided. Otherwise, the name and product_id are extracted from the id. A AttributeValidationError will be raised if it conflicts with an existing product_id and/or name.

Type

str, immutable

property is_modified

Whether any attributes were changed (see state).

True if any of the attribute values changed since the last time this catalog object was retrieved or saved. False otherwise.

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

Type

bool

jpx_layer_index

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

Defaults to 0.

Type

int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of the catalog object.

The name of a named catalog object is unique within a product and object type (images and bands). The name can contain alphanumeric characters, -, _, and . up to 2000 characters. If the id contains a name, it will be used instead. Once set, it cannot be changed.

Sortable.

Type

str, immutable

nodata

A value representing missing data in a pixel in this band.

Type

float, optional

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

product

The product instance this catalog object belongs to.

If given, it is used to retrieve the product_id.

Filterable.

Type

Product, immutable

product_id

The id of the product this catalog object belongs to.

If the id contains a product id, it will be used instead. Once set, it cannot be changed.

Filterable, sortable.

Type

str, immutable

readers

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

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

Type

list(str), optional

resolution

The spatial resolution of this band.

Filterable, sortable.

Type

Resolution, optional

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, optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

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

Filterable.

Type

list, optional

type

The type of this band, directly corresponding to a Band derived class.

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class 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 or BandType

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 to the owners of a catalog object. See this note.

Type

list(str), optional

class GenericBand(**kwargs)[source]

A generic kind of band not fitting any other type.

For example mapping physical values like temperature or angles.

Instantiating a generic band indicates that you want to create a new Descartes Labs catalog generic band. If you instead want to retrieve an existing catalog generic band use Band.get(), or if you’re not sure use GenericBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

band_index

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

colormap

A custom colormap for this band.

colormap_name

Name of a predefined colormap for display purposes.

created

The point in time this object was created.

data_range

The range of pixel values stored in the band.

data_type

The data type for pixel values in this band.

description

A description with further details on the band.

display_range

The range of pixel values for display purposes.

extra_properties

A dictionary of up to 50 key/value pairs.

file_index

The 0-based index into the list of source files.

id

An optional unique identifier for this object.

is_modified

Whether any attributes were changed (see state).

jpx_layer_index

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

modified

The point in time this object was last modified.

name

The name of the catalog object.

nodata

A value representing missing data in a pixel in this band.

owners

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

physical_range

A physical range that pixel values map to.

physical_range_unit

Unit of the physical range

product

The product instance this catalog object belongs to.

product_id

The id of the product this catalog object belongs to.

readers

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

resolution

The spatial resolution of this band.

sort_order

A number defining the default sort order for bands within a product.

state

The state of this catalog object.

tags

A list of up to 20 tags.

type

The type of this band, directly corresponding to a Band derived class.

writers

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

Methods

delete(id[, client])

Delete the catalog object with the given id.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

reload()

Reload all attributes from the Descartes Labs catalog.

save([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client])

A search query for all bands.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises
classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters
Returns

True if this object was successfully deleted. False if the object was not found.

Return type

bool

Raises

Example

>>> Image.delete('my-image-id')
classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

classmethod make_valid_name(name)

Replace invalid characters in the given name and return a valid name.

Replace any sequence of invalid characters in a string with a single _ character to create a valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

Note that it is possible that two unique invalid names may turn into duplicate valid names if the uniqueness is located in the same sequence of invalid characters.

Parameters

name (str) – A name for a Band or Image that may contain invalid characters.

Returns

A name for a Band or Image that does not contain any invalid characters.

Return type

str

Example

>>> name = "This is ań @#$^*% ïñvalid name!!!!"
>>> band = SpectralBand()
>>> band.name = Band.make_valid_name(name)
>>> band.name
'This_is_a_valid_name_'
>>>
reload()

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save(extra_attributes=None)

Saves this object to the Descartes Labs catalog.

If this instance was created using the constructor, it will be in the UNSAVED state and is considered a new Descartes Labs catalog object that must be created. If the catalog object already exists in this case, this method will raise a BadRequestError.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and any of its values were changed, it will be in the MODIFIED state and the existing catalog object will be updated.

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no extra_attributes parameter is given, nothing will happen.

Parameters

extra_attributes (dict, optional) – A dictionary of attributes that should be sent to the catalog along with attributes already set on this object. Empty by default. If not empty, and the object is in the SAVED state, it is updated in the Descartes Labs catalog even though no attributes were modified.

Raises

Example

>>> new_product = Product(
...     id="my-product",
...     name="My Product",
...     description="This is a test product"
... )
>>> new_product.state
<DocumentState.UNSAVED: 'unsaved'>
>>> new_product.save()
>>> # ids will be automatically prefixed by the Descartes Labs catalog
>>> # with your organization id
>>> new_product.id
my_org_id:my-product
>>> # Now you can retrieve the product and update it
>>> existing_product = Product.get(new_product.id)
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> existing_product.name = "My Updated Product"
>>> existing_product.state
<DocumentState.MODIFIED: 'modified'>
>>> existing_product.save()
>>> existing_product.state
<DocumentState.SAVED: 'saved'>
>>> # After you delete it...
>>> existing_product.delete()
True
>>> product.state
<DocumentState.DELETED: 'deleted'>
classmethod search(client=None)

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

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters

ignore_errors (bool, optional) – False by default. When set to True, it will suppress AttributeValidationError and AttributeError. Any given attribute that causes one of these two exceptions will be ignored, all other attributes will be set to the given values.

Raises
  • AttributeValidationError – If one or more of the attributes being updated are immutable.

  • AttributeError – If one or more of the attributes are not part of this catalog object.

  • DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('physical_range', 'physical_range_unit', 'colormap_name', 'colormap', 'description', 'type', 'sort_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'id', 'name', 'product_id', 'product', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'created', 'modified')
band_index

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

Type

int

colormap

A custom colormap for this band.

A list of tuples, where each nested tuple is a 4-tuple of RGBA values to map pixels whose value is the index of the list. 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), optional

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 or Colormap, optional

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

data_range

The range of pixel values stored in the band.

The two floats are the minimum and maximum pixel values stored in this band.

Type

tuple(float, float)

data_type

The data type for pixel values in this band.

Type

str or DataType

description

A description with further details on the band.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, optional

display_range

The range of pixel values for display purposes.

The two floats are the minimum and maximum values indicating a default reasonable range of pixel values usd when rastering this band for display purposes.

Type

tuple(float, float)

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary 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

file_index

The 0-based index into the list of source files.

If there are multiple files, it maps the band index to the file index. It defaults to 0 (first file).

Type

int, optional

id

An optional unique identifier for this object.

The identifier for a named catalog object is the concatenation of the product_id and name, separated by a colon. It will be generated from the product_id and the name if not provided. Otherwise, the name and product_id are extracted from the id. A AttributeValidationError will be raised if it conflicts with an existing product_id and/or name.

Type

str, immutable

property is_modified

Whether any attributes were changed (see state).

True if any of the attribute values changed since the last time this catalog object was retrieved or saved. False otherwise.

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

Type

bool

jpx_layer_index

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

Defaults to 0.

Type

int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of the catalog object.

The name of a named catalog object is unique within a product and object type (images and bands). The name can contain alphanumeric characters, -, _, and . up to 2000 characters. If the id contains a name, it will be used instead. Once set, it cannot be changed.

Sortable.

Type

str, immutable

nodata

A value representing missing data in a pixel in this band.

Type

float, optional

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

physical_range

A physical range that pixel values map to.

Type

tuple(float, float), optional

physical_range_unit

Unit of the physical range

Type

str, optional

product

The product instance this catalog object belongs to.

If given, it is used to retrieve the product_id.

Filterable.

Type

Product, immutable

product_id

The id of the product this catalog object belongs to.

If the id contains a product id, it will be used instead. Once set, it cannot be changed.

Filterable, sortable.

Type

str, immutable

readers

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

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

Type

list(str), optional

resolution

The spatial resolution of this band.

Filterable, sortable.

Type

Resolution, optional

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, optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

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

Filterable.

Type

list, optional

type

The type of this band, directly corresponding to a Band derived class.

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class 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 or BandType

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 to the owners of a catalog object. See this note.

Type

list(str), optional

class DerivedBand(**kwargs)[source]

A band with pixel values computed from the data in other bands.

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.

Instantiating a derived band can only be done through Band.get(), or Band.search().

Parameters
  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – You cannot set any additional keyword arguments as a derived band is readonly.

Attributes

ATTRIBUTES

Built-in immutable sequence.

bands

List of bands used in the derived band pixel function.

created

The point in time this object was created.

data_range

The range of pixel values stored in the band.

data_type

The data type for pixel values in this band.

description

A description with further details on the band.

extra_properties

A dictionary of up to 50 key/value pairs.

function_name

Name of the function applied to create this derived band.

id

A unique identifier for this object.

is_modified

Whether any attributes were changed (see state).

modified

The point in time this object was last modified.

name

The name of the derived band, globally unique.

owners

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

physical_range

A physical range that pixel values map to.

readers

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

state

The state of this catalog object.

tags

A list of up to 20 tags.

writers

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

Methods

delete(id[, client])

You cannot delete a derived band.

exists(id[, client])

Checks if an object exists in the Descartes Labs catalog.

get(id[, client])

Get an existing object from the Descartes Labs catalog.

get_many(ids[, ignore_missing, client])

Get existing objects from the Descartes Labs catalog.

get_or_create(id[, client])

Get an existing object from the Descartes Labs catalog or create a new object.

reload()

Reload all attributes from the Descartes Labs catalog.

save()

You cannot save a derived band.

search([client])

A search query for all objects of the type this class represents.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update(**kwargs)

You cannot update a derived band.

delete()[source]

You cannot delete a derived band.

Raises

NotImplementedError – This method is not supported for DerivedBands.

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

You cannot delete a derived band.

Raises

NotImplementedError – This method is not supported for DerivedBands.

classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters
Returns

Returns True if the given id represents an existing object in the Descartes Labs catalog and False if not.

Return type

bool

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get(id, client=None)

Get an existing object from the Descartes Labs catalog.

If the Descartes Labs catalog object is found, it will be returned in the SAVED state. Subsequent changes will put the instance in the MODIFIED state, and you can use save() to commit those changes and update the Descartes Labs catalog object. Also see the example for save().

For bands, if you request a specific band type, for example SpectralBand.get(), you will only receive that type. Use Band.get() to receive any type.

Parameters
Returns

The object you requested, or None if an object with the given id does not exist in the Descartes Labs catalog.

Return type

CatalogObject or None

Raises

ClientError or ServerErrorSpurious exception that can occur during a network request.

classmethod get_many(ids, ignore_missing=False, client=None)

Get existing objects from the Descartes Labs catalog.

All returned Descartes Labs catalog objects will be in the SAVED state. Also see get().

For bands, if you request a specific band type, for example SpectralBand.get_many(), you will only receive that type. Use Band.get_many() to receive any type.

Parameters
  • ids (list(str)) – A list of identifiers for the objects you are requesting.

  • ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the Descartes Labs catalog. False by default which raises the exception.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

List of the objects you requested in the same order.

Return type

list(CatalogObject)

Raises
classmethod get_or_create(id, client=None, **kwargs)

Get an existing object from the Descartes Labs catalog or create a new object.

If the Descartes Labs catalog object is found, and the remainder of the arguments do not differ from the values in the retrieved instance, it will be returned in the SAVED state.

If the Descartes Labs catalog object is found, and the remainder of the arguments update one or more values in the instance, it will be returned in the MODIFIED state.

If the Descartes Labs catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters
  • id (str) – The id of the object you are requesting.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

  • kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns

The requested catalog object that was retrieved or created.

Return type

CatalogObject

reload()

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This may be necessary if there are concurrent updates and the object in the Descartes Labs catalog was updated from another client. The instance state must be in the SAVED state.

If you want to revert a modified object to its original one, you should use get() on the object class with the object’s id.

Raises

Example

>>> p = Product("my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state
<DocumentState.SAVED: 'saved'>
>>> p.reload()
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 47, in wrapper
    return f(self, *args, **kwargs)
File "/usr/lib/python3/site-packages/descarteslabs/catalog/catalog_base.py", line 879, in reload
    """Reload all attributes from the Descartes Labs catalog.
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id)
>>> p.state
<DocumentState.SAVED: 'saved'>
save()[source]

You cannot save a derived band.

Raises

NotImplementedError – This method is not supported for DerivedBands.

classmethod search(client=None)

A search query for all objects of the type this class represents.

Parameters

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.

Returns

An instance of the Search class.

Return type

Search

Example

>>> search = Product.search().limit(10)
>>> for result in search:
        print(result.name)
serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters
  • modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.

  • jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(**kwargs)[source]

You cannot update a derived band.

Raises

NotImplementedError – This method is not supported for DerivedBands.

ATTRIBUTES = ('name', 'description', 'data_type', 'data_range', 'physical_range', 'bands', 'function_name', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'id', 'created', 'modified')
bands

List of bands used in the derived band pixel function.

Filterable

Type

list(str), readonly

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

data_range

The range of pixel values stored in the band.

The two floats are the minimum and maximum pixel values stored in this band.

Type

tuple(float, float), readonly

data_type

The data type for pixel values in this band.

Type

str or DataType, readonly

description

A description with further details on the band.

The description can be up to 80,000 characters and is used by Search.find_text().

Searchable

Type

str, readonly

extra_properties

A dictionary of up to 50 key/value pairs.

The keys of this dictonary 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

function_name

Name of the function applied to create this derived band.

Type

str, readonly

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

property is_modified

Whether any attributes were changed (see state).

True if any of the attribute values changed since the last time this catalog object was retrieved or saved. False otherwise.

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

Type

bool

modified

The point in time this object was last modified.

Filterable, sortable.

Type

datetime, readonly

name

The name of the derived band, globally unique.

Filterable, sortable.

Type

str, 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

physical_range

A physical range that pixel values map to.

Type

tuple(float, float), optional

readers

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

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

Type

list(str), optional

property state

The state of this catalog object.

Type

DocumentState

tags

A list of up to 20 tags.

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 to the owners of a catalog object. See this note.

Type

list(str), optional