Bands¶
A data band in images of a specific product. |
|
A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum. |
|
A band that lies in the microwave spectrum, often from SAR or passive radar sensors. |
|
A binary band where by convention a 0 means masked and 1 means non-masked. |
|
A band that maps a finite set of values that may not be continuous. |
|
A generic kind of band not fitting any other type. |
|
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
,vendor_order
,data_type
,nodata
,data_range
,display_range
,resolution
,band_index
,file_index
,jpx_layer_index
.vendor_band_name
.To create a new band instantiate one of those specialized classes:
SpectralBand
: A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum. Specific attributes:physical_range
,physical_range_unit
,wavelength_nm_center
,wavelength_nm_min
,wavelength_nm_max
,wavelength_nm_fwhm
,processing_levels
,derived_params
.MicrowaveBand
: A band that lies in the microwave spectrum, often from SAR or passive radar sensors. Specific attributes:frequency
,bandwidth
,physical_range
,physical_range_unit
.MaskBand
: A binary band where by convention a 0 means masked and 1 means non-masked. Thedata_range
anddisplay_range
for masks is implicitly[0, 1]
. Specific attributes:is_alpha
.ClassBand
: A band that maps a finite set of values that may not be continuous to classification categories (e.g. a land use classification). A visualization with straight pixel values is typically not useful, so commonly acolormap
is used. Specific attributes:colormap
,colormap_name
,class_labels
.GenericBand
: A generic type for bands that are not represented by the other band types, e.g., mapping physical values like temperature or angles. Specific attributes:colormap
,colormap_name
,physical_range
,physical_range_unit
,processing_levels
,derived_params
.
-
delete
()¶ Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Raises
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
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.
-
classmethod
delete
(id, client=None) Delete the catalog object with the given
id
.- Parameters
id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
True
if this object was successfully deleted.False
if the object was not found.- Return type
bool
- Raises
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
-
classmethod
exists
(id, client=None)¶ Checks if an object exists in the Descartes Labs catalog.
- Parameters
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 validname
forBand
orImage
. 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 aBand
orImage
. 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 aBand
orImage
that may contain invalid characters.- Returns
A
name
for aBand
orImage
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_'
-
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 theBand
base class to search all types of bands or classesSpectralBand
,MicrowaveBand
,MaskBand
,ClassBand
andGenericBand
to search only a specific type of band.- Parameters
client (
CatalogClient
) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns
An instance of the
Search
class- Return type
-
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 useSpectralBand.get_or_create()
. You can also useBand.search()
. Also see the example forsave()
.- Parameters
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict, optional) – With the exception of readonly attributes (
created
,modified
) and with the exception of properties (ATTRIBUTES
,is_modified
, andstate
), any attribute listed below can also be used as a keyword argument. Also seeATTRIBUTES
.
-
delete
()¶ Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Raises
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
Attributes:
The 0-based index into the source data to access this band.
The point in time this object was created.
The range of pixel values stored in the band.
The data type for pixel values in this band.
Derived Band Parameters Attribute.
A description with further details on the band.
The range of pixel values for display purposes.
A dictionary of up to 50 key/value pairs.
The 0-based index into the list of source files.
An optional unique identifier for this object.
Whether any attributes were changed (see
state
).The 0-based layer index if the source data is JPEG2000 with layers.
The point in time this object was last modified.
The name of the catalog object.
A value representing missing data in a pixel in this band.
User, group, or organization IDs that own this object.
A physical range that pixel values map to.
Unit of the physical range.
An attribute that contains properties (key/value pairs).
The product instance this catalog object belongs to.
The id of the product this catalog object belongs to.
User, group, or organization IDs that can read this object.
The spatial resolution of this band.
A number defining the default sort order for bands within a product.
The state of this catalog object.
A list of up to 20 tags.
The type of this band, directly corresponding to a
Band
derived class.The name of the band in the source file.
A number defining the ordering of bands within a product as defined by the data vendor.
Weighted center of min/max responsiveness of the band, in nm.
Full width at half maximum value of the wavelength spread, in nm.
Maximum wavelength this band is sensitive to, in nm.
Minimum wavelength this band is sensitive to, in nm.
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.
-
classmethod
delete
(id, client=None) Delete the catalog object with the given
id
.- Parameters
id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
True
if this object was successfully deleted.False
if the object was not found.- Return type
bool
- Raises
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
-
classmethod
exists
(id, client=None)¶ Checks if an object exists in the Descartes Labs catalog.
- Parameters
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 forsave()
.- 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. Theget_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 seeATTRIBUTES
).
- Returns
The requested catalog object that was retrieved or created.
- Return type
-
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 validname
forBand
orImage
. 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 aBand
orImage
. 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 aBand
orImage
that may contain invalid characters.- Returns
A
name
for aBand
orImage
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’sid
.- Raises
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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 aBadRequestError
.If this instance was retrieved using
get()
,get_or_create()
or any other way (for example as part of asearch()
), and any of its values were changed, it will be in theMODIFIED
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 asearch()
), and none of its values were changed, it will be in theSAVED
state, and if noextra_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
ConflictError – If you’re trying to create a new object and the object with given
id
already exists in the Descartes Labs catalog.BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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)¶ A search query for all bands.
Returns an instance of the
Search
class configured for searching bands. Call this on theBand
base class to search all types of bands or classesSpectralBand
,MicrowaveBand
,MaskBand
,ClassBand
andGenericBand
to search only a specific type of band.- Parameters
client (
CatalogClient
) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns
An instance of the
Search
class- Return type
-
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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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 toTrue
, it will suppressAttributeValidationError
andAttributeError
. 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', 'wavelength_nm_center', 'wavelength_nm_min', 'wavelength_nm_max', 'wavelength_nm_fwhm', 'description', 'type', 'sort_order', 'vendor_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'vendor_band_name', 'processing_levels', 'derived_params', '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)
-
derived_params
¶ Derived Band Parameters Attribute.
-
function
¶ Name of the function to apply. Required.
- Type
str
-
bands
¶ Names of the bands used as input to the function. Required.
- Type
list(str)
-
source_type
¶ Optional index into the named parameter (an array) for the band.
- Type
int
-
-
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
andname
, separated by a colon. It will be generated from theproduct_id
and thename
if not provided. Otherwise, thename
andproduct_id
are extracted from theid
. AAttributeValidationError
will be raised if it conflicts with an existingproduct_id
and/orname
.- 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 theid
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
-
processing_levels
¶ An attribute that contains properties (key/value pairs).
Can be set using a dictionary of items or any
Mapping
, or an instance of this attribute. All keys must be string and values can be string or an iterable ofProcessingStepAttribute
items (or compatible mapping).ProcessingLevelsAttribute
behaves similar to dictionaries.
-
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
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
, andGenericBand
. 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
-
vendor_band_name
¶ The name of the band in the source file.
Some source file types require that the band be indexed by name rather than by the
band_index
.- Type
str, optional
-
vendor_order
¶ A number defining the ordering of bands within a product as defined by the data vendor. 1-based. Used for indexing
c6s_dlsr
. Generally only used internally by certain core products.Sortable.
- Type
int, optional
-
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 useMicrowaveBand.get_or_create()
. You can also useBand.search()
. Also see the example forsave()
.- Parameters
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict, optional) – With the exception of readonly attributes (
created
,modified
) and with the exception of properties (ATTRIBUTES
,is_modified
, andstate
), any attribute listed below can also be used as a keyword argument. Also seeATTRIBUTES
.
-
delete
()¶ Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Raises
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
Attributes:
The 0-based index into the source data to access this band.
Chirp bandwidth of the sensor in MHz.
The point in time this object was created.
The range of pixel values stored in the band.
The data type for pixel values in this band.
A description with further details on the band.
The range of pixel values for display purposes.
A dictionary of up to 50 key/value pairs.
The 0-based index into the list of source files.
Center frequency of the observed microwave in GHz.
An optional unique identifier for this object.
Whether any attributes were changed (see
state
).The 0-based layer index if the source data is JPEG2000 with layers.
The point in time this object was last modified.
The name of the catalog object.
A value representing missing data in a pixel in this band.
User, group, or organization IDs that own this object.
A physical range that pixel values map to.
Unit of the physical range.
The product instance this catalog object belongs to.
The id of the product this catalog object belongs to.
User, group, or organization IDs that can read this object.
The spatial resolution of this band.
A number defining the default sort order for bands within a product.
The state of this catalog object.
A list of up to 20 tags.
The type of this band, directly corresponding to a
Band
derived class.The name of the band in the source file.
A number defining the ordering of bands within a product as defined by the data vendor.
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.
-
classmethod
delete
(id, client=None) Delete the catalog object with the given
id
.- Parameters
id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
True
if this object was successfully deleted.False
if the object was not found.- Return type
bool
- Raises
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
-
classmethod
exists
(id, client=None)¶ Checks if an object exists in the Descartes Labs catalog.
- Parameters
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 forsave()
.- 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. Theget_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 seeATTRIBUTES
).
- Returns
The requested catalog object that was retrieved or created.
- Return type
-
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 validname
forBand
orImage
. 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 aBand
orImage
. 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 aBand
orImage
that may contain invalid characters.- Returns
A
name
for aBand
orImage
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’sid
.- Raises
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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 aBadRequestError
.If this instance was retrieved using
get()
,get_or_create()
or any other way (for example as part of asearch()
), and any of its values were changed, it will be in theMODIFIED
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 asearch()
), and none of its values were changed, it will be in theSAVED
state, and if noextra_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
ConflictError – If you’re trying to create a new object and the object with given
id
already exists in the Descartes Labs catalog.BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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)¶ A search query for all bands.
Returns an instance of the
Search
class configured for searching bands. Call this on theBand
base class to search all types of bands or classesSpectralBand
,MicrowaveBand
,MaskBand
,ClassBand
andGenericBand
to search only a specific type of band.- Parameters
client (
CatalogClient
) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns
An instance of the
Search
class- Return type
-
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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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 toTrue
, it will suppressAttributeValidationError
andAttributeError
. 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', 'physical_range', 'physical_range_unit', 'description', 'type', 'sort_order', 'vendor_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'vendor_band_name', 'processing_levels', 'derived_params', '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)
-
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
andname
, separated by a colon. It will be generated from theproduct_id
and thename
if not provided. Otherwise, thename
andproduct_id
are extracted from theid
. AAttributeValidationError
will be raised if it conflicts with an existingproduct_id
and/orname
.- 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 theid
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
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
, andGenericBand
. 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
-
vendor_band_name
¶ The name of the band in the source file.
Some source file types require that the band be indexed by name rather than by the
band_index
.- Type
str, optional
-
vendor_order
¶ A number defining the ordering of bands within a product as defined by the data vendor. 1-based. Used for indexing
c6s_dlsr
. Generally only used internally by certain core products.Sortable.
- Type
int, 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
MaskBand
(**kwargs)[source]¶ A binary band where by convention a 0 means masked and 1 means non-masked.
The
data_range
anddisplay_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 useMaskBand.get_or_create()
. You can also useBand.search()
. Also see the example forsave()
.- Parameters
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict, optional) – With the exception of readonly attributes (
created
,modified
) and with the exception of properties (ATTRIBUTES
,is_modified
, andstate
), any attribute listed below can also be used as a keyword argument. Also seeATTRIBUTES
.
-
delete
()¶ Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Raises
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
Attributes:
The 0-based index into the source data to access this band.
The point in time this object was created.
[0, 1].
The data type for pixel values in this band.
A description with further details on the band.
[0, 1].
A dictionary of up to 50 key/value pairs.
The 0-based index into the list of source files.
An optional unique identifier for this object.
Whether this band should be useable as an alpha band during rastering.
Whether any attributes were changed (see
state
).The 0-based layer index if the source data is JPEG2000 with layers.
The point in time this object was last modified.
The name of the catalog object.
A value representing missing data in a pixel in this band.
User, group, or organization IDs that own this object.
The product instance this catalog object belongs to.
The id of the product this catalog object belongs to.
User, group, or organization IDs that can read this object.
The spatial resolution of this band.
A number defining the default sort order for bands within a product.
The state of this catalog object.
A list of up to 20 tags.
The type of this band, directly corresponding to a
Band
derived class.The name of the band in the source file.
A number defining the ordering of bands within a product as defined by the data vendor.
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.
-
classmethod
delete
(id, client=None) Delete the catalog object with the given
id
.- Parameters
id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
True
if this object was successfully deleted.False
if the object was not found.- Return type
bool
- Raises
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
-
classmethod
exists
(id, client=None)¶ Checks if an object exists in the Descartes Labs catalog.
- Parameters
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 forsave()
.- 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. Theget_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 seeATTRIBUTES
).
- Returns
The requested catalog object that was retrieved or created.
- Return type
-
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 validname
forBand
orImage
. 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 aBand
orImage
. 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 aBand
orImage
that may contain invalid characters.- Returns
A
name
for aBand
orImage
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’sid
.- Raises
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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 aBadRequestError
.If this instance was retrieved using
get()
,get_or_create()
or any other way (for example as part of asearch()
), and any of its values were changed, it will be in theMODIFIED
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 asearch()
), and none of its values were changed, it will be in theSAVED
state, and if noextra_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
ConflictError – If you’re trying to create a new object and the object with given
id
already exists in the Descartes Labs catalog.BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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)¶ A search query for all bands.
Returns an instance of the
Search
class configured for searching bands. Call this on theBand
base class to search all types of bands or classesSpectralBand
,MicrowaveBand
,MaskBand
,ClassBand
andGenericBand
to search only a specific type of band.- Parameters
client (
CatalogClient
) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns
An instance of the
Search
class- Return type
-
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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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 toTrue
, it will suppressAttributeValidationError
andAttributeError
. 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', 'vendor_order', 'data_type', 'nodata', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'vendor_band_name', 'processing_levels', 'derived_params', '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
-
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
andname
, separated by a colon. It will be generated from theproduct_id
and thename
if not provided. Otherwise, thename
andproduct_id
are extracted from theid
. AAttributeValidationError
will be raised if it conflicts with an existingproduct_id
and/orname
.- 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 asdescarteslabs.scenes.scenecollection.SceneCollection.mosaic()
ordescarteslabs.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 theid
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
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
, andGenericBand
. 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
-
vendor_band_name
¶ The name of the band in the source file.
Some source file types require that the band be indexed by name rather than by the
band_index
.- Type
str, optional
-
vendor_order
¶ A number defining the ordering of bands within a product as defined by the data vendor. 1-based. Used for indexing
c6s_dlsr
. Generally only used internally by certain core products.Sortable.
- Type
int, 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
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 useClassBand.get_or_create()
. You can also useBand.search()
. Also see the example forsave()
.- Parameters
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict, optional) – With the exception of readonly attributes (
created
,modified
) and with the exception of properties (ATTRIBUTES
,is_modified
, andstate
), any attribute listed below can also be used as a keyword argument. Also seeATTRIBUTES
.
-
delete
()¶ Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Raises
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
Attributes:
The 0-based index into the source data to access this band.
A list of labels.
A custom colormap for this band.
Name of a predefined colormap for display purposes.
The point in time this object was created.
The range of pixel values stored in the band.
The data type for pixel values in this band.
A description with further details on the band.
The range of pixel values for display purposes.
A dictionary of up to 50 key/value pairs.
The 0-based index into the list of source files.
An optional unique identifier for this object.
Whether any attributes were changed (see
state
).The 0-based layer index if the source data is JPEG2000 with layers.
The point in time this object was last modified.
The name of the catalog object.
A value representing missing data in a pixel in this band.
User, group, or organization IDs that own this object.
The product instance this catalog object belongs to.
The id of the product this catalog object belongs to.
User, group, or organization IDs that can read this object.
The spatial resolution of this band.
A number defining the default sort order for bands within a product.
The state of this catalog object.
A list of up to 20 tags.
The type of this band, directly corresponding to a
Band
derived class.The name of the band in the source file.
A number defining the ordering of bands within a product as defined by the data vendor.
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.
-
classmethod
delete
(id, client=None) Delete the catalog object with the given
id
.- Parameters
id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
True
if this object was successfully deleted.False
if the object was not found.- Return type
bool
- Raises
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
-
classmethod
exists
(id, client=None)¶ Checks if an object exists in the Descartes Labs catalog.
- Parameters
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 forsave()
.- 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. Theget_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 seeATTRIBUTES
).
- Returns
The requested catalog object that was retrieved or created.
- Return type
-
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 validname
forBand
orImage
. 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 aBand
orImage
. 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 aBand
orImage
that may contain invalid characters.- Returns
A
name
for aBand
orImage
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’sid
.- Raises
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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 aBadRequestError
.If this instance was retrieved using
get()
,get_or_create()
or any other way (for example as part of asearch()
), and any of its values were changed, it will be in theMODIFIED
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 asearch()
), and none of its values were changed, it will be in theSAVED
state, and if noextra_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
ConflictError – If you’re trying to create a new object and the object with given
id
already exists in the Descartes Labs catalog.BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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)¶ A search query for all bands.
Returns an instance of the
Search
class configured for searching bands. Call this on theBand
base class to search all types of bands or classesSpectralBand
,MicrowaveBand
,MaskBand
,ClassBand
andGenericBand
to search only a specific type of band.- Parameters
client (
CatalogClient
) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns
An instance of the
Search
class- Return type
-
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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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 toTrue
, it will suppressAttributeValidationError
andAttributeError
. 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', 'vendor_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'vendor_band_name', 'processing_levels', 'derived_params', '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 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)
-
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
andname
, separated by a colon. It will be generated from theproduct_id
and thename
if not provided. Otherwise, thename
andproduct_id
are extracted from theid
. AAttributeValidationError
will be raised if it conflicts with an existingproduct_id
and/orname
.- 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 theid
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
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
, andGenericBand
. 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
-
vendor_band_name
¶ The name of the band in the source file.
Some source file types require that the band be indexed by name rather than by the
band_index
.- Type
str, optional
-
vendor_order
¶ A number defining the ordering of bands within a product as defined by the data vendor. 1-based. Used for indexing
c6s_dlsr
. Generally only used internally by certain core products.Sortable.
- Type
int, 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
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 useGenericBand.get_or_create()
. You can also useBand.search()
. Also see the example forsave()
.- Parameters
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict, optional) – With the exception of readonly attributes (
created
,modified
) and with the exception of properties (ATTRIBUTES
,is_modified
, andstate
), any attribute listed below can also be used as a keyword argument. Also seeATTRIBUTES
.
-
delete
()¶ Delete this catalog object from the Descartes Labs catalog.
Once deleted, you cannot use the catalog object and should release any references.
- Raises
DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.
Attributes:
The 0-based index into the source data to access this band.
A custom colormap for this band.
Name of a predefined colormap for display purposes.
The point in time this object was created.
The range of pixel values stored in the band.
The data type for pixel values in this band.
Derived Band Parameters Attribute.
A description with further details on the band.
The range of pixel values for display purposes.
A dictionary of up to 50 key/value pairs.
The 0-based index into the list of source files.
An optional unique identifier for this object.
Whether any attributes were changed (see
state
).The 0-based layer index if the source data is JPEG2000 with layers.
The point in time this object was last modified.
The name of the catalog object.
A value representing missing data in a pixel in this band.
User, group, or organization IDs that own this object.
A physical range that pixel values map to.
Unit of the physical range.
An attribute that contains properties (key/value pairs).
The product instance this catalog object belongs to.
The id of the product this catalog object belongs to.
User, group, or organization IDs that can read this object.
The spatial resolution of this band.
A number defining the default sort order for bands within a product.
The state of this catalog object.
A list of up to 20 tags.
The type of this band, directly corresponding to a
Band
derived class.The name of the band in the source file.
A number defining the ordering of bands within a product as defined by the data vendor.
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.
-
classmethod
delete
(id, client=None) Delete the catalog object with the given
id
.- Parameters
id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
True
if this object was successfully deleted.False
if the object was not found.- Return type
bool
- Raises
ConflictError – If the object has related objects (bands, images) that exist.
ClientError or ServerError – Spurious exception that can occur during a network request.
Example
>>> Image.delete('my-image-id')
-
classmethod
exists
(id, client=None)¶ Checks if an object exists in the Descartes Labs catalog.
- Parameters
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 forsave()
.- 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. Theget_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 seeATTRIBUTES
).
- Returns
The requested catalog object that was retrieved or created.
- Return type
-
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 validname
forBand
orImage
. 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 aBand
orImage
. 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 aBand
orImage
that may contain invalid characters.- Returns
A
name
for aBand
orImage
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’sid
.- Raises
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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 aBadRequestError
.If this instance was retrieved using
get()
,get_or_create()
or any other way (for example as part of asearch()
), and any of its values were changed, it will be in theMODIFIED
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 asearch()
), and none of its values were changed, it will be in theSAVED
state, and if noextra_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
ConflictError – If you’re trying to create a new object and the object with given
id
already exists in the Descartes Labs catalog.BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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)¶ A search query for all bands.
Returns an instance of the
Search
class configured for searching bands. Call this on theBand
base class to search all types of bands or classesSpectralBand
,MicrowaveBand
,MaskBand
,ClassBand
andGenericBand
to search only a specific type of band.- Parameters
client (
CatalogClient
) – ACatalogClient
instance to use for requests to the Descartes Labs catalog.- Returns
An instance of the
Search
class- Return type
-
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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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 toTrue
, it will suppressAttributeValidationError
andAttributeError
. 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', 'vendor_order', 'data_type', 'nodata', 'data_range', 'display_range', 'resolution', 'band_index', 'file_index', 'jpx_layer_index', 'vendor_band_name', 'processing_levels', 'derived_params', '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)
-
derived_params
¶ Derived Band Parameters Attribute.
-
function
¶ Name of the function to apply. Required.
- Type
str
-
bands
¶ Names of the bands used as input to the function. Required.
- Type
list(str)
-
source_type
¶ Optional index into the named parameter (an array) for the band.
- Type
int
-
-
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
andname
, separated by a colon. It will be generated from theproduct_id
and thename
if not provided. Otherwise, thename
andproduct_id
are extracted from theid
. AAttributeValidationError
will be raised if it conflicts with an existingproduct_id
and/orname
.- 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 theid
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
-
processing_levels
¶ An attribute that contains properties (key/value pairs).
Can be set using a dictionary of items or any
Mapping
, or an instance of this attribute. All keys must be string and values can be string or an iterable ofProcessingStepAttribute
items (or compatible mapping).ProcessingLevelsAttribute
behaves similar to dictionaries.
-
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
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
, andGenericBand
. 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
-
vendor_band_name
¶ The name of the band in the source file.
Some source file types require that the band be indexed by name rather than by the
band_index
.- Type
str, optional
-
vendor_order
¶ A number defining the ordering of bands within a product as defined by the data vendor. 1-based. Used for indexing
c6s_dlsr
. Generally only used internally by certain core products.Sortable.
- Type
int, 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
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()
, orBand.search()
.- Parameters
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.kwargs (dict, optional) – You cannot set any additional keyword arguments as a derived band is readonly.
-
delete
()[source]¶ You cannot delete a derived band.
- Raises
NotImplementedError – This method is not supported for DerivedBands.
Attributes:
List of bands used in the derived band pixel function.
The point in time this object was created.
The range of pixel values stored in the band.
The data type for pixel values in this band.
A description with further details on the band.
A dictionary of up to 50 key/value pairs.
Name of the function applied to create this derived band.
A unique identifier for this object.
Whether any attributes were changed (see
state
).The point in time this object was last modified.
The name of the derived band, globally unique.
User, group, or organization IDs that own this object.
A physical range that pixel values map to.
User, group, or organization IDs that can read this object.
The state of this catalog object.
A list of up to 20 tags.
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.
-
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
id (str) – The id of the object.
client (CatalogClient, optional) – A
CatalogClient
instance to use for requests to the Descartes Labs catalog. Theget_default_client()
will be used if not set.
- Returns
Returns
True
if the givenid
represents an existing object in the Descartes Labs catalog andFalse
if not.- Return type
bool
- Raises
ClientError or ServerError – Spurious 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 theMODIFIED
state, and you can usesave()
to commit those changes and update the Descartes Labs catalog object. Also see the example forsave()
.For bands, if you request a specific band type, for example
SpectralBand.get()
, you will only receive that type. UseBand.get()
to receive any type.- 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. Theget_default_client()
will be used if not set.
- Returns
The object you requested, or
None
if an object with the givenid
does not exist in the Descartes Labs catalog.- Return type
CatalogObject
or None- Raises
ClientError or ServerError – Spurious 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 seeget()
.For bands, if you request a specific band type, for example
SpectralBand.get_many()
, you will only receive that type. UseBand.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. Theget_default_client()
will be used if not set.
- Returns
List of the objects you requested in the same order.
- Return type
list(
CatalogObject
)- Raises
NotFoundError – If any of the requested objects do not exist in the Descartes Labs catalog and
ignore_missing
isFalse
.ClientError or ServerError – Spurious exception that can occur during a network request.
-
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 forsave()
.- 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. Theget_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 seeATTRIBUTES
).
- Returns
The requested catalog object that was retrieved or created.
- Return type
-
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’sid
.- Raises
ValueError – If the catalog object is not in the
SAVED
state.DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.
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
()[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. Theget_default_client()
will be used if not set.- Returns
An instance of the
Search
class.- Return type
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 toTrue
, 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 toFalse
, the serialized data will directly contain the attributes of the catalog object. If set toTrue
, the serialized data will follow the exact JSONAPI with a top-leveldata
element which containsid
,type
, andattributes
. 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
-
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
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