Image

Image

An image with raster data.

ImageUpload

The status object returned when you upload an image using upload() or upload_ndarray().


class Image(**kwargs)[source]

An image with raster data.

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

Parameters

Attributes

ATTRIBUTES

Built-in immutable sequence.

SUPPORTED_DATATYPES

Built-in immutable sequence.

acquired

Timestamp when the image was captured by its sensor or created.

acquired_end

Timestamp when the image capture by its sensor was completed.

alt_cloud_fraction

Fraction of pixels which are obscured by clouds.

area

Surface area the image covers.

azimuth_angle

Sensor azimuth angle in degrees.

bits_per_pixel

Average bits of data per pixel per band.

bright_fraction

Fraction of the image that has reflectance greater than .4 in the blue band.

cloud_fraction

Fraction of pixels which are obscured by clouds.

created

The point in time this object was created.

cs_code

The coordinate reference system used by the image as an EPSG or ESRI code.

extra_properties

A dictionary of up to 50 key/value pairs.

files

The list of files holding data for this image.

fill_fraction

Fraction of this image which has data.

geometry

Geometry representing the image coverage.

geotrans

GDAL-style geotransform matrix.

id

An optional unique identifier for this object.

incidence_angle

Sensor incidence angle in degrees.

is_modified

Whether any attributes were changed (see state).

modified

The point in time this object was last modified.

name

The name of the catalog object.

owners

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

preview_file

A GCS URL with a georeferenced image.

preview_url

An external (http) URL to a preview image.

processing_pipeline_id

Identifier for the pipeline that processed this image from raw data.

product

The product instance this catalog object belongs to.

product_id

The id of the product this catalog object belongs to.

projection

The spatial reference system used by the image.

provider_id

Id that uniquely ties this image to an entity as understood by the data provider.

provider_url

An external (http) URL that has more details about the image

published

Timestamp when the data provider published this image.

readers

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

reflectance_scale

Scale factors converting TOA radiances to TOA reflectances.

roll_angle

Applicable only to Landsat 8, roll angle in degrees.

satellite_id

Id of the capturing satellite/sensor among a constellation of many satellites.

solar_azimuth_angle

Solar azimuth angle at capture time.

solar_elevation_angle

Solar elevation angle at capture time.

state

The state of this catalog object.

storage_state

Storage state of the image.

tags

A list of up to 20 tags.

view_angle

Sensor view angle in degrees.

writers

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

x_pixels

X dimension of the image in pixels.

y_pixels

Y dimension of the image in pixels.

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.

image_uploads()

A search query for all uploads for this image created by this user.

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

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

upload(files[, upload_options, overwrite])

Uploads imagery from a file (or files).

upload_ndarray(ndarray[, upload_options, …])

Uploads imagery from an ndarray to be ingested as an Image.

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

image_uploads()[source]

A search query for all uploads for this image created by this user.

Returns

A Search instance configured to find all uploads for this image.

Return type

Search

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

>>> from descarteslabs.catalog import SpectralBand, Band
>>> 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

>>> from descarteslabs.catalog import Product
>>> p = Product(id="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):
    ...
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

>>> from descarteslabs.catalog import Product
>>> 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)[source]

A search query for all images.

Return an ImageSearch instance for searching images in the Descartes Labs catalog. This instance extends the Search class with the summary() and summary_interval() methods which return summary statistics about the images that match the search query.

Parameters

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog.

Returns

An instance of the ImageSearch class

Return type

ImageSearch

Example

>>> from descarteslabs.catalog import Image
>>> search = Image.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(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.

upload(files, upload_options=None, overwrite=False)[source]

Uploads imagery from a file (or files).

Uploads imagery from a file (or files) in GeoTIFF or JP2 format to be ingested as an Image.

The Image must be in the state UNSAVED. The product or product_id attribute, the name attribute, and the acquired attribute must all be set. If either the cs_code or projection attributes is set (deprecated), it must agree with the projection defined in the file, otherwise an upload error will occur during processing.

Parameters
  • files (str or io.IOBase or iterable of same) – File or files to be uploaded. Can be string with path to the file in the local filesystem, or an opened file (io.IOBase), or an iterable of either of these when multiple files make up the image.

  • upload_options (ImageUploadOptions, optional) – Control of the upload process.

  • overwrite (bool, optional) – If True, then permit overwriting of an existing image with the same id in the catalog. Defaults to False. Note that in all cases, the image object must have a state of UNSAVED.

Returns

An ImageUpload instance which can be used to check the status or wait on the asynchronous upload process to complete.

Return type

ImageUpload

Raises
  • ValueError – If any improper arguments are supplied.

  • DeletedObjectError – If this image was deleted.

upload_ndarray(ndarray, upload_options=None, raster_meta=None, overviews=None, overview_resampler=None, overwrite=False)[source]

Uploads imagery from an ndarray to be ingested as an Image.

The Image must be in the state UNSAVED. The product or product_id attribute, the name attribute, and the acquired attribute must all be set. Either (but not both) the cs_code or projection attributes must be set, or the raster_meta parameter must be provided. Similarly, either the geotrans attribute must be set or raster_meta must be provided.

Note that one of the spatial reference attributes (cs_code or projection), or the geotrans attribute can be specified explicitly in the image, or the raster_meta parameter can be specified. Likewise, overviews and overview_resampler can be specified explicitly, or via the upload_options parameter.

Parameters
  • ndarray (np.array) – A numpy array with image data, either with 2 dimensions of shape (x, y) for a single band or with 3 dimensions of shape (band, x, y) for any number of bands. If providing a 3d array the first dimension must index the bands. The dtype of the array must also be one of the following: [uint8, int8, uint16, int16, uint32, int32, float32, float64]

  • upload_options (ImageUploadOptions, optional) – Control of the upload process.

  • raster_meta (dict, optional) – Metadata returned from the Raster.ndarray() request which generated the initial data for the ndarray being uploaded. Specifying geotrans and one of the spatial reference attributes (cs_code or projection) is unnecessary in this case but will take precedence over the value in raster_meta.

  • overviews (list(int), optional) – Overview resolution magnification factors e.g. [2, 4] would make two overviews at 2x and 4x the native resolution. Maximum number of overviews allowed is 16. Can also be set in the upload_options parameter.

  • overview_resampler (str, optional) – Resampler algorithm to use when building overviews. Controls how pixels are combined to make lower res pixels in overviews. Allowed resampler algorithms are: [nearest, average, gauss, cubic, cubicspline, lanczos, average_mp, average_magphase, mode]. Can also be set in the upload_options parameter.

  • overwrite (bool, optional) – If True, then permit overwriting of an existing image with the same id in the catalog. Defaults to False. Note that in all cases, the image object must have a state of UNSAVED.

Raises
  • ValueError – If any improper arguments are supplied.

  • DeletedObjectError – If this image was deleted.

Returns

An ImageUpload instance which can be used to check the status or wait on the asynchronous upload process to complete.

Return type

ImageUpload

ATTRIBUTES = ('geometry', 'cs_code', 'projection', 'geotrans', 'x_pixels', 'y_pixels', 'acquired', 'acquired_end', 'published', 'storage_state', 'files', 'area', 'azimuth_angle', 'bits_per_pixel', 'bright_fraction', 'cloud_fraction', 'alt_cloud_fraction', 'processing_pipeline_id', 'fill_fraction', 'incidence_angle', 'reflectance_scale', 'roll_angle', 'solar_azimuth_angle', 'solar_elevation_angle', 'view_angle', 'satellite_id', 'provider_id', 'provider_url', 'preview_url', 'preview_file', 'id', 'name', 'product_id', 'product', 'owners', 'readers', 'writers', 'extra_properties', 'tags', 'created', 'modified')
SUPPORTED_DATATYPES = ('uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64')
acquired

Timestamp when the image was captured by its sensor or created.

Filterable, sortable.

Type

str or datetime

acquired_end

Timestamp when the image capture by its sensor was completed.

Filterable, sortable.

Type

str or datetime, optional

alt_cloud_fraction

Fraction of pixels which are obscured by clouds.

This is as per an alternative algorithm. See the product documentation in the Descartes Labs catalog for more information.

Filterable, sortable.

Type

float, optional

area

Surface area the image covers.

Filterable, sortable.

Type

float, optional

azimuth_angle

Sensor azimuth angle in degrees.

Filterable, sortable.

Type

float, optional

bits_per_pixel

Average bits of data per pixel per band.

Type

list(float), optional

bright_fraction

Fraction of the image that has reflectance greater than .4 in the blue band.

Filterable, sortable.

Type

float, optional

cloud_fraction

Fraction of pixels which are obscured by clouds.

Filterable, sortable.

Type

float, optional

created

The point in time this object was created.

Filterable, sortable.

Type

datetime, readonly

cs_code

The coordinate reference system used by the image as an EPSG or ESRI code.

An example of a EPSG code is "EPSG:4326". One of cs_code and projection is required. If both are set and disagree, cs_code takes precedence.

Type

str

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

files

The list of files holding data for this image.

Type

list(File)

fill_fraction

Fraction of this image which has data.

Filterable, sortable.

Type

float, optional

geometry

Geometry representing the image coverage.

Filterable

(use ImageSearch.intersects to search based on geometry)

Type

str or shapely.geometry.base.BaseGeometry

geotrans

GDAL-style geotransform matrix.

A GDAL-style geotransform matrix that transforms pixel coordinates into the spatial reference system defined by the cs_code or projection attributes.

Type

tuple of six float elements, optional if REMOTE

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

incidence_angle

Sensor incidence angle in degrees.

Filterable, sortable.

Type

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

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

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

preview_file

A GCS URL with a georeferenced image.

Use a GCS URL (gs://...`) with appropriate access permissions. This referenced image can be used to raster the image in a preview context, generally low resolution. It should be a 3-band (RBG) or a 4-band (RGBA) image suitable for visual preview. (It’s not expected to conform to the bands of the products.)

Type

str, optional

preview_url

An external (http) URL to a preview image.

This image could be inlined in a UI to show a preview for the image.

Type

str, optional

processing_pipeline_id

Identifier for the pipeline that processed this image from raw data.

Filterable, sortable.

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

projection

The spatial reference system used by the image.

The projection can be specified as either a proj.4 string or a a WKT string. One of cs_code and projection is required. If both are set and disagree, cs_code takes precedence.

Type

str

provider_id

Id that uniquely ties this image to an entity as understood by the data provider.

Filterable, sortable.

Type

str, optional

provider_url

An external (http) URL that has more details about the image

Type

str, optional

published

Timestamp when the data provider published this image.

Filterable, sortable.

Type

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

reflectance_scale

Scale factors converting TOA radiances to TOA reflectances.

Type

list(float), optional

roll_angle

Applicable only to Landsat 8, roll angle in degrees.

Filterable, sortable.

Type

float, optional

satellite_id

Id of the capturing satellite/sensor among a constellation of many satellites.

Filterable, sortable.

Type

str, optional

solar_azimuth_angle

Solar azimuth angle at capture time.

Filterable, sortable.

Type

float, optional

solar_elevation_angle

Solar elevation angle at capture time.

Filterable, sortable.

Type

float, optional

property state

The state of this catalog object.

Type

DocumentState

storage_state

Storage state of the image.

The state is AVAILABLE if the data is available and can be rastered, REMOTE if the data is not currently available.

Filterable, sortable.

Type

str or StorageState

tags

A list of up to 20 tags.

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

Filterable.

Type

list, optional

view_angle

Sensor view angle in degrees.

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

x_pixels

X dimension of the image in pixels.

Type

int, optional if REMOTE

y_pixels

Y dimension of the image in pixels.

Type

int, optional if REMOTE

class ImageUpload(**kwargs)[source]

The status object returned when you upload an image using upload() or upload_ndarray().

Attributes

ATTRIBUTES

Built-in immutable sequence.

events

List of events pertaining to the upload process.

id

Globally unique identifier for the upload.

image

Image instance with all desired metadata fields.

image_id

Image id of the image for this imagery.

image_upload_options

Control of the upload process.

is_modified

Whether any attributes were changed (see state).

product_id

Product id of the product for this imagery.

state

The state of this catalog object.

status

Current job status.

user

The User ID of the user requesting the upload.

Methods

cancel()

Cancel the upload if it is not yet completed.

delete(id[, client, ignore_missing])

You cannot delete an ImageUpload.

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([extra_attributes])

Saves this object to the Descartes Labs catalog.

search([client, includes])

A search query for all uploads.

serialize([modified_only, jsonapi_format])

Serialize the catalog object into json.

update([ignore_errors])

Update multiple attributes at once using the given keyword arguments.

wait_for_completion([timeout, …])

Wait for the upload to complete.

cancel()[source]

Cancel the upload if it is not yet completed.

Note that if the upload process is already running, it cannot be canceled unless a retryable error occurs.

Raises
  • NotFoundError – If the object no longer exists.

  • ValueError – If the catalog object is not in the SAVED state.

  • DeletedObjectError – If this catalog object was deleted.

  • ConflictError – If the upload has a current status which does not allow it to be canceled.

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

You cannot delete an ImageUpload.

Raises

NotImplementedError – This method is not supported for ImageUploads.

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()[source]

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this upload object. The instance state must be in the SAVED state. If the status changes to ImageUploadStatus.SUCCESS then the image instance is also reloaded so that it contains the full state of the newly loaded image.

Raises
  • NotFoundError – If the object no longer exists.

  • ValueError – If the catalog object is not in the SAVED state.

  • DeletedObjectError – If this catalog object was deleted.

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

>>> from descarteslabs.catalog import Product
>>> 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, includes=True)[source]

A search query for all uploads.

Return an Search instance for searching image uploads.

Parameters
  • includes (bool) – Controls the inclusion of events. If True, includes these objects. If False, no events are included. Defaults to True.

  • client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog.

Returns

An instance of the Search class

Return type

Search

Example

>>> from descarteslabs.catalog import (
...     ImageUpload,
...     ImageUploadStatus,
...     properties as p,
... )
>>> search = ImageUpload.search().filter(p.status == ImageUploadStatus.FAILURE)
>>> for result in search: 
...     print(result) 
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.

wait_for_completion(timeout=None, warn_transient_errors=True)[source]

Wait for the upload to complete.

Parameters
  • timeout (int, optional) – If specified, will wait up to specified number of seconds and will raise a concurrent.futures.TimeoutError if the upload has not completed.

  • warn_transient_errors (bool, optional, default True) – Any transient errors while periodically checking upload status are suppressed. If True, those errors will be printed as warnings.

Raises

concurrent.futures.TimeoutError – If the specified timeout elapses and the upload has not completed.

ATTRIBUTES = ('id', 'product_id', 'image_id', 'image', 'image_upload_options', 'user', 'resumable_urls', 'status', 'events', 'created', 'modified')
events

List of events pertaining to the upload process.

Type

list(ImageUploadEvent)

id

Globally unique identifier for the upload.

Type

str

image

Image instance with all desired metadata fields.

Note that any values will override those determined from the image files themselves.

Type

Image

image_id

Image id of the image for this imagery.

The image id for the Image to which this imagery will be uploaded. This is identical to image.id.

Filterable.

Type

str

image_upload_options

Control of the upload process.

Type

ImageUploadOptions

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

product_id

Product id of the product for this imagery.

The product id for the Product to which this imagery will be uploaded.

Filterable, sortable.

Type

str

property state

The state of this catalog object.

Type

DocumentState

status

Current job status.

To retrieve the latest status, use reload().

Filterable, sortable.

Type

str or ImageUploadStatus

user

The User ID of the user requesting the upload.

Filterable, sortable.

Type

str