Bands

`Band`	A data band in images of a specific product.
`SpectralBand`	A band that lies somewhere on the visible/NIR/SWIR electro-optical wavelength spectrum.
`MicrowaveBand`	A band that lies in the microwave spectrum, often from SAR or passive radar sensors.
`MaskBand`	A binary band where by convention a 0 means masked and 1 means non-masked.
`ClassBand`	A band that maps a finite set of values that may not be continuous.
`GenericBand`	A generic kind of band not fitting any other type.
`BandCollection`

class Band(*args, **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. The data_range and display_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 a colormap 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.

Methods:

`delete`(id[, client])	Delete the catalog object with the given `id`.
`exists`(id[, client, headers])	Checks if an object exists in the EarthOne catalog.
`get`(id[, client, request_params, headers])	Get an existing object from the EarthOne catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the EarthOne catalog.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`search`([client, request_params, headers])	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 EarthOne catalog. The get_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') 

There is also an instance delete method that can be used to delete an object. It accepts no parameters and does not return anything. Once deleted, you cannot use the catalog object and should release any references.

classmethod exists(id, client=None, headers=None)

Checks if an object exists in the EarthOne catalog.

Parameters:

id (str) – The id of the object.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

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

Return type:

bool

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get(id, client=None, request_params=None, headers=None)

Get an existing object from the EarthOne catalog.

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

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

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

The object you requested, or None if an object with the given id does not exist in the EarthOne 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, request_params=None, headers=None)

Get existing objects from the EarthOne catalog.

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

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

Parameters:

ids (list(str)) – A list of identifiers for the objects you are requesting.
ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the EarthOne catalog. False by default which raises the exception.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the EarthOne catalog and ignore_missing is False.
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 valid name for Band or Image. Since the Band and Image names have a limited character set, this method will replace any sequence of characters outside that character set with a single _ character. The returned string is a safe name to use for a Band or Image. The given string is unchanged.

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

Parameters:: name (str) – A name for a Band or Image that may contain invalid characters.
Returns:: A name for a Band or Image that does not contain any invalid characters.
Return type:: str

Example

>>> from earthdaily.earthone.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, request_params=None, headers=None)[source]

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters:: client (CatalogClient) – A CatalogClient instance to use for requests to the EarthOne catalog.
Returns:: An instance of the Search class
Return type:: Search

class SpectralBand(*args, **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 EarthOne catalog spectral band. If you instead want to retrieve an existing catalog spectral band use Band.get(), or if you’re not sure use SpectralBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters:

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_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, and state), any attribute listed below can also be used as a keyword argument. Also see ATTRIBUTES.

Methods:

`delete`(id[, client])	Delete the catalog object with the given `id`.
`exists`(id[, client, headers])	Checks if an object exists in the EarthOne catalog.
`get`(id[, client, request_params, headers])	Get an existing object from the EarthOne catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the EarthOne catalog.
`get_or_create`(id[, client, request_params, ...])	Get an existing object from the EarthOne catalog or create a new object.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`reload`([request_params, headers])	Reload all attributes from the EarthOne catalog.
`save`([request_params, headers])	Saves this object to the EarthOne catalog.
`search`([client, request_params, headers])	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.

Attributes:

`ATTRIBUTES`
`band_index`	The 0-based index into the source data to access this band.
`created`	The point in time this object was created.
`data_range`	The range of pixel values stored in the band.
`data_type`	The data type for pixel values in this band.
`derived_params`	Derived Band Parameters Attribute.
`description`	A description with further details on the band.
`display_range`	The range of pixel values for display purposes.
`extra_properties`	A dictionary of up to 50 key/value pairs.
`file_index`	The 0-based index into the list of source files.
`id`	An optional unique identifier for this object.
`is_modified`	Whether any attributes were changed (see `state`).
`jpx_layer_index`	The 0-based layer index if the source data is JPEG2000 with layers.
`modified`	The point in time this object was last modified.
`name`	The name of the catalog object.
`nodata`	A value representing missing data in a pixel in this band.
`physical_range`	A physical range that pixel values map to.
`physical_range_unit`	Unit of the physical range.
`processing_levels`	An attribute that contains properties (key/value pairs).
`product`	The product instance this catalog object belongs to.
`product_id`	The id of the product this catalog object belongs to.
`resolution`	The spatial resolution of this band.
`sort_order`	A number defining the default sort order for bands within a product.
`state`	The state of this catalog object.
`tags`	A list of up to 32 tags, each up to 1000 bytes long.
`type`	The type of this band, directly corresponding to a `Band` derived class.
`vendor_band_name`	The name of the band in the source file.
`vendor_order`	A number defining the ordering of bands within a product as defined by the data vendor.
`wavelength_nm_center`	Weighted center of min/max responsiveness of the band, in nm.
`wavelength_nm_fwhm`	Full width at half maximum value of the wavelength spread, in nm.
`wavelength_nm_max`	Maximum wavelength this band is sensitive to, in nm.
`wavelength_nm_min`	Minimum wavelength this band is sensitive to, in nm.

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 EarthOne catalog. The get_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') 

There is also an instance delete method that can be used to delete an object. It accepts no parameters and does not return anything. Once deleted, you cannot use the catalog object and should release any references.

classmethod exists(id, client=None, headers=None)

Checks if an object exists in the EarthOne catalog.

Parameters:

id (str) – The id of the object.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

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

Return type:

bool

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get(id, client=None, request_params=None, headers=None)

Get an existing object from the EarthOne catalog.

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

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

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

The object you requested, or None if an object with the given id does not exist in the EarthOne 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, request_params=None, headers=None)

Get existing objects from the EarthOne catalog.

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

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

Parameters:

ids (list(str)) – A list of identifiers for the objects you are requesting.
ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the EarthOne catalog. False by default which raises the exception.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the EarthOne catalog and ignore_missing is False.
ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get_or_create(id, client=None, request_params=None, headers=None, **kwargs)

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

If the EarthOne 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 EarthOne 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 EarthOne catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.
kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

classmethod make_valid_name(name)

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

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

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

Parameters:: name (str) – A name for a Band or Image that may contain invalid characters.
Returns:: A name for a Band or Image that does not contain any invalid characters.
Return type:: str

Example

>>> from earthdaily.earthone.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(request_params=None, headers=None)

Reload all attributes from the EarthOne catalog.

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

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

Raises:

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.

save(request_params=None, headers=None)

Saves this object to the EarthOne catalog.

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

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

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

Parameters:

request_params (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 EarthOne catalog even though no attributes were modified.
headers (dict, optional) – A dictionary of header keys and values to be sent with the request.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the EarthOne 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.

classmethod search(client=None, request_params=None, headers=None)

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters:: client (CatalogClient) – A CatalogClient instance to use for requests to the EarthOne catalog.
Returns:: An instance of the Search class
Return type:: Search

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.
jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

AttributeValidationError – If one or more of the attributes being updated are immutable.
AttributeError – If one or more of the attributes are not part of this catalog object.
DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('physical_range', 'physical_range_unit', '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', 'extra_properties', 'tags', 'created', 'modified')

band_index

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

Type:: int

created

The point in time this object was created.

Filterable, sortable.

Type:: datetime, readonly

data_range

The range of pixel values stored in the band.

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

Type:: tuple(float, float)

data_type

The data type for pixel values in this band.

Type:: str or DataType

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 dictionary must be strings, and the values of this dictionary can be strings or numbers. This allows for more structured custom metadata to be associated with objects.

Type:: dict, optional

file_index

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

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

Type:: int, optional

id

An optional unique identifier for this object.

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

Type:: str, immutable

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

jpx_layer_index

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

Defaults to 0.

Type:: int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

name

The name of the catalog object.

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

Sortable.

Type:: str, immutable

nodata

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

Type:: float, optional

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 of ProcessingStepAttribute 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

resolution

The spatial resolution of this band.

Filterable, sortable.

Type:: Resolution, optional

sort_order

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

If not set for newly created bands, this will default to the current maximum sort order + 1 in the product.

Sortable.

Type:: int, optional

property state

The state of this catalog object.

Type:: DocumentState

tags

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

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

Filterable.

Type:: list, optional

type

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

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class used. The type of a band does not necessarily affect how it is rastered, it mainly conveys useful information about the data it contains.

Filterable.

Type:: str or BandType

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

class MicrowaveBand(*args, **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 EarthOne catalog microwave band. If you instead want to retrieve an existing catalog microwave band use Band.get(), or if you’re not sure use MicrowaveBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters:

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_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, and state), any attribute listed below can also be used as a keyword argument. Also see ATTRIBUTES.

Methods:

`delete`(id[, client])	Delete the catalog object with the given `id`.
`exists`(id[, client, headers])	Checks if an object exists in the EarthOne catalog.
`get`(id[, client, request_params, headers])	Get an existing object from the EarthOne catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the EarthOne catalog.
`get_or_create`(id[, client, request_params, ...])	Get an existing object from the EarthOne catalog or create a new object.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`reload`([request_params, headers])	Reload all attributes from the EarthOne catalog.
`save`([request_params, headers])	Saves this object to the EarthOne catalog.
`search`([client, request_params, headers])	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.

Attributes:

`ATTRIBUTES`
`band_index`	The 0-based index into the source data to access this band.
`bandwidth`	Chirp bandwidth of the sensor in MHz.
`created`	The point in time this object was created.
`data_range`	The range of pixel values stored in the band.
`data_type`	The data type for pixel values in this band.
`description`	A description with further details on the band.
`display_range`	The range of pixel values for display purposes.
`extra_properties`	A dictionary of up to 50 key/value pairs.
`file_index`	The 0-based index into the list of source files.
`frequency`	Center frequency of the observed microwave in GHz.
`id`	An optional unique identifier for this object.
`is_modified`	Whether any attributes were changed (see `state`).
`jpx_layer_index`	The 0-based layer index if the source data is JPEG2000 with layers.
`modified`	The point in time this object was last modified.
`name`	The name of the catalog object.
`nodata`	A value representing missing data in a pixel in this band.
`physical_range`	A physical range that pixel values map to.
`physical_range_unit`	Unit of the physical range.
`product`	The product instance this catalog object belongs to.
`product_id`	The id of the product this catalog object belongs to.
`resolution`	The spatial resolution of this band.
`sort_order`	A number defining the default sort order for bands within a product.
`state`	The state of this catalog object.
`tags`	A list of up to 32 tags, each up to 1000 bytes long.
`type`	The type of this band, directly corresponding to a `Band` derived class.
`vendor_band_name`	The name of the band in the source file.
`vendor_order`	A number defining the ordering of bands within a product as defined by the data vendor.

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 EarthOne catalog. The get_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') 

There is also an instance delete method that can be used to delete an object. It accepts no parameters and does not return anything. Once deleted, you cannot use the catalog object and should release any references.

classmethod exists(id, client=None, headers=None)

Checks if an object exists in the EarthOne catalog.

Parameters:

id (str) – The id of the object.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

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

Return type:

bool

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get(id, client=None, request_params=None, headers=None)

Get an existing object from the EarthOne catalog.

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

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

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

The object you requested, or None if an object with the given id does not exist in the EarthOne 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, request_params=None, headers=None)

Get existing objects from the EarthOne catalog.

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

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

Parameters:

ids (list(str)) – A list of identifiers for the objects you are requesting.
ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the EarthOne catalog. False by default which raises the exception.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the EarthOne catalog and ignore_missing is False.
ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get_or_create(id, client=None, request_params=None, headers=None, **kwargs)

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

If the EarthOne 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 EarthOne 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 EarthOne catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.
kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

classmethod make_valid_name(name)

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

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

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

Parameters:: name (str) – A name for a Band or Image that may contain invalid characters.
Returns:: A name for a Band or Image that does not contain any invalid characters.
Return type:: str

Example

>>> from earthdaily.earthone.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(request_params=None, headers=None)

Reload all attributes from the EarthOne catalog.

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

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

Raises:

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.

save(request_params=None, headers=None)

Saves this object to the EarthOne catalog.

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

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

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

Parameters:

request_params (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 EarthOne catalog even though no attributes were modified.
headers (dict, optional) – A dictionary of header keys and values to be sent with the request.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the EarthOne 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.

classmethod search(client=None, request_params=None, headers=None)

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters:: client (CatalogClient) – A CatalogClient instance to use for requests to the EarthOne catalog.
Returns:: An instance of the Search class
Return type:: Search

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.
jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

AttributeValidationError – If one or more of the attributes being updated are immutable.
AttributeError – If one or more of the attributes are not part of this catalog object.
DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('frequency', 'bandwidth', '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', 'extra_properties', 'tags', 'created', 'modified')

band_index

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

Type:: int

bandwidth

Chirp bandwidth of the sensor in MHz.

Filterable, sortable.

Type:: float, optional

created

The point in time this object was created.

Filterable, sortable.

Type:: datetime, readonly

data_range

The range of pixel values stored in the band.

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

Type:: tuple(float, float)

data_type

The data type for pixel values in this band.

Type:: str or DataType

description

A description with further details on the band.

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

Searchable

Type:: str, optional

display_range

The range of pixel values for display purposes.

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

Type:: tuple(float, float)

extra_properties

A dictionary of up to 50 key/value pairs.

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

Type:: dict, optional

file_index

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

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

Type:: int, optional

frequency

Center frequency of the observed microwave in GHz.

Filterable, sortable.

Type:: float, optional

id

An optional unique identifier for this object.

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

Type:: str, immutable

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

jpx_layer_index

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

Defaults to 0.

Type:: int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

name

The name of the catalog object.

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

Sortable.

Type:: str, immutable

nodata

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

Type:: float, optional

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

resolution

The spatial resolution of this band.

Filterable, sortable.

Type:: Resolution, optional

sort_order

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

If not set for newly created bands, this will default to the current maximum sort order + 1 in the product.

Sortable.

Type:: int, optional

property state

The state of this catalog object.

Type:: DocumentState

tags

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

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

Filterable.

Type:: list, optional

type

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

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class used. The type of a band does not necessarily affect how it is rastered, it mainly conveys useful information about the data it contains.

Filterable.

Type:: str or BandType

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

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

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

The data_range and display_range for masks is implicitly (0, 1).

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

Parameters:

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_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, and state), any attribute listed below can also be used as a keyword argument. Also see ATTRIBUTES.

Methods:

`delete`(id[, client])	Delete the catalog object with the given `id`.
`exists`(id[, client, headers])	Checks if an object exists in the EarthOne catalog.
`get`(id[, client, request_params, headers])	Get an existing object from the EarthOne catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the EarthOne catalog.
`get_or_create`(id[, client, request_params, ...])	Get an existing object from the EarthOne catalog or create a new object.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`reload`([request_params, headers])	Reload all attributes from the EarthOne catalog.
`save`([request_params, headers])	Saves this object to the EarthOne catalog.
`search`([client, request_params, headers])	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.

Attributes:

`ATTRIBUTES`
`band_index`	The 0-based index into the source data to access this band.
`created`	The point in time this object was created.
`data_range`	[0, 1].
`data_type`	The data type for pixel values in this band.
`description`	A description with further details on the band.
`display_range`	[0, 1].
`extra_properties`	A dictionary of up to 50 key/value pairs.
`file_index`	The 0-based index into the list of source files.
`id`	An optional unique identifier for this object.
`is_alpha`	Whether this band should be useable as an alpha band during rastering.
`is_modified`	Whether any attributes were changed (see `state`).
`jpx_layer_index`	The 0-based layer index if the source data is JPEG2000 with layers.
`modified`	The point in time this object was last modified.
`name`	The name of the catalog object.
`nodata`	A value representing missing data in a pixel in this band.
`product`	The product instance this catalog object belongs to.
`product_id`	The id of the product this catalog object belongs to.
`resolution`	The spatial resolution of this band.
`sort_order`	A number defining the default sort order for bands within a product.
`state`	The state of this catalog object.
`tags`	A list of up to 32 tags, each up to 1000 bytes long.
`type`	The type of this band, directly corresponding to a `Band` derived class.
`vendor_band_name`	The name of the band in the source file.
`vendor_order`	A number defining the ordering of bands within a product as defined by the data vendor.

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 EarthOne catalog. The get_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') 

There is also an instance delete method that can be used to delete an object. It accepts no parameters and does not return anything. Once deleted, you cannot use the catalog object and should release any references.

classmethod exists(id, client=None, headers=None)

Checks if an object exists in the EarthOne catalog.

Parameters:

id (str) – The id of the object.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

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

Return type:

bool

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get(id, client=None, request_params=None, headers=None)

Get an existing object from the EarthOne catalog.

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

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

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

The object you requested, or None if an object with the given id does not exist in the EarthOne 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, request_params=None, headers=None)

Get existing objects from the EarthOne catalog.

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

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

Parameters:

ids (list(str)) – A list of identifiers for the objects you are requesting.
ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the EarthOne catalog. False by default which raises the exception.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the EarthOne catalog and ignore_missing is False.
ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get_or_create(id, client=None, request_params=None, headers=None, **kwargs)

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

If the EarthOne 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 EarthOne 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 EarthOne catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.
kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

classmethod make_valid_name(name)

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

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

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

Parameters:: name (str) – A name for a Band or Image that may contain invalid characters.
Returns:: A name for a Band or Image that does not contain any invalid characters.
Return type:: str

Example

>>> from earthdaily.earthone.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(request_params=None, headers=None)

Reload all attributes from the EarthOne catalog.

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

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

Raises:

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.

save(request_params=None, headers=None)

Saves this object to the EarthOne catalog.

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

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

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

Parameters:

request_params (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 EarthOne catalog even though no attributes were modified.
headers (dict, optional) – A dictionary of header keys and values to be sent with the request.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the EarthOne 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.

classmethod search(client=None, request_params=None, headers=None)

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters:: client (CatalogClient) – A CatalogClient instance to use for requests to the EarthOne catalog.
Returns:: An instance of the Search class
Return type:: Search

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.
jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

AttributeValidationError – If one or more of the attributes being updated are immutable.
AttributeError – If one or more of the attributes are not part of this catalog object.
DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('is_alpha', 'data_range', 'display_range', 'description', 'type', 'sort_order', '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', 'extra_properties', 'tags', 'created', 'modified')

band_index

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

Type:: int

created

The point in time this object was created.

Filterable, sortable.

Type:: datetime, readonly

data_range

[0, 1].

Type:: tuple(float, float), readonly

data_type

The data type for pixel values in this band.

Type:: str or DataType

description

A description with further details on the band.

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

Searchable

Type:: str, optional

display_range

[0, 1].

Type:: tuple(float, float), readonly

extra_properties

A dictionary of up to 50 key/value pairs.

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

Type:: dict, optional

file_index

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

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

Type:: int, optional

id

An optional unique identifier for this object.

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

Type:: str, immutable

is_alpha

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

This enables special behavior for this band during rastering. If this is True and the band appears as the last band in a raster operation (such as earthdaily.earthone.catalog.imagecollection.ImageCollection.mosaic() or earthdaily.earthone.catalog.imagecollection.ImageCollection.stack()) pixels with a value of 0 in this band will be treated as transparent.

Type:: bool, optional

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

jpx_layer_index

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

Defaults to 0.

Type:: int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

name

The name of the catalog object.

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

Sortable.

Type:: str, immutable

nodata

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

Type:: float, optional

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

resolution

The spatial resolution of this band.

Filterable, sortable.

Type:: Resolution, optional

sort_order

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

If not set for newly created bands, this will default to the current maximum sort order + 1 in the product.

Sortable.

Type:: int, optional

property state

The state of this catalog object.

Type:: DocumentState

tags

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

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

Filterable.

Type:: list, optional

type

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

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class used. The type of a band does not necessarily affect how it is rastered, it mainly conveys useful information about the data it contains.

Filterable.

Type:: str or BandType

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

class ClassBand(*args, **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 EarthOne catalog class band. If you instead want to retrieve an existing catalog class band use Band.get(), or if you’re not sure use ClassBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters:

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_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, and state), any attribute listed below can also be used as a keyword argument. Also see ATTRIBUTES.

Methods:

`delete`(id[, client])	Delete the catalog object with the given `id`.
`exists`(id[, client, headers])	Checks if an object exists in the EarthOne catalog.
`get`(id[, client, request_params, headers])	Get an existing object from the EarthOne catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the EarthOne catalog.
`get_or_create`(id[, client, request_params, ...])	Get an existing object from the EarthOne catalog or create a new object.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`reload`([request_params, headers])	Reload all attributes from the EarthOne catalog.
`save`([request_params, headers])	Saves this object to the EarthOne catalog.
`search`([client, request_params, headers])	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.

Attributes:

`ATTRIBUTES`
`band_index`	The 0-based index into the source data to access this band.
`class_labels`	A list of labels.
`colormap`	A custom colormap for this band.
`colormap_name`	Name of a predefined colormap for display purposes.
`created`	The point in time this object was created.
`data_range`	The range of pixel values stored in the band.
`data_type`	The data type for pixel values in this band.
`description`	A description with further details on the band.
`display_range`	The range of pixel values for display purposes.
`extra_properties`	A dictionary of up to 50 key/value pairs.
`file_index`	The 0-based index into the list of source files.
`id`	An optional unique identifier for this object.
`is_modified`	Whether any attributes were changed (see `state`).
`jpx_layer_index`	The 0-based layer index if the source data is JPEG2000 with layers.
`modified`	The point in time this object was last modified.
`name`	The name of the catalog object.
`nodata`	A value representing missing data in a pixel in this band.
`product`	The product instance this catalog object belongs to.
`product_id`	The id of the product this catalog object belongs to.
`resolution`	The spatial resolution of this band.
`sort_order`	A number defining the default sort order for bands within a product.
`state`	The state of this catalog object.
`tags`	A list of up to 32 tags, each up to 1000 bytes long.
`type`	The type of this band, directly corresponding to a `Band` derived class.
`vendor_band_name`	The name of the band in the source file.
`vendor_order`	A number defining the ordering of bands within a product as defined by the data vendor.

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 EarthOne catalog. The get_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') 

There is also an instance delete method that can be used to delete an object. It accepts no parameters and does not return anything. Once deleted, you cannot use the catalog object and should release any references.

classmethod exists(id, client=None, headers=None)

Checks if an object exists in the EarthOne catalog.

Parameters:

id (str) – The id of the object.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

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

Return type:

bool

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get(id, client=None, request_params=None, headers=None)

Get an existing object from the EarthOne catalog.

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

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

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

The object you requested, or None if an object with the given id does not exist in the EarthOne 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, request_params=None, headers=None)

Get existing objects from the EarthOne catalog.

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

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

Parameters:

ids (list(str)) – A list of identifiers for the objects you are requesting.
ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the EarthOne catalog. False by default which raises the exception.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the EarthOne catalog and ignore_missing is False.
ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get_or_create(id, client=None, request_params=None, headers=None, **kwargs)

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

If the EarthOne 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 EarthOne 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 EarthOne catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.
kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

classmethod make_valid_name(name)

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

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

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

Parameters:: name (str) – A name for a Band or Image that may contain invalid characters.
Returns:: A name for a Band or Image that does not contain any invalid characters.
Return type:: str

Example

>>> from earthdaily.earthone.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(request_params=None, headers=None)

Reload all attributes from the EarthOne catalog.

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

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

Raises:

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.

save(request_params=None, headers=None)

Saves this object to the EarthOne catalog.

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

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

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

Parameters:

request_params (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 EarthOne catalog even though no attributes were modified.
headers (dict, optional) – A dictionary of header keys and values to be sent with the request.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the EarthOne 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.

classmethod search(client=None, request_params=None, headers=None)

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters:: client (CatalogClient) – A CatalogClient instance to use for requests to the EarthOne catalog.
Returns:: An instance of the Search class
Return type:: Search

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.
jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

AttributeValidationError – If one or more of the attributes being updated are immutable.
AttributeError – If one or more of the attributes are not part of this catalog object.
DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('colormap_name', 'colormap', 'class_labels', 'description', 'type', 'sort_order', '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', '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)

data_type

The data type for pixel values in this band.

Type:: str or DataType

description

A description with further details on the band.

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

Searchable

Type:: str, optional

display_range

The range of pixel values for display purposes.

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

Type:: tuple(float, float)

extra_properties

A dictionary of up to 50 key/value pairs.

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

Type:: dict, optional

file_index

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

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

Type:: int, optional

id

An optional unique identifier for this object.

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

Type:: str, immutable

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

jpx_layer_index

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

Defaults to 0.

Type:: int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

name

The name of the catalog object.

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

Sortable.

Type:: str, immutable

nodata

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

Type:: float, optional

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

resolution

The spatial resolution of this band.

Filterable, sortable.

Type:: Resolution, optional

sort_order

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

If not set for newly created bands, this will default to the current maximum sort order + 1 in the product.

Sortable.

Type:: int, optional

property state

The state of this catalog object.

Type:: DocumentState

tags

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

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

Filterable.

Type:: list, optional

type

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

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class used. The type of a band does not necessarily affect how it is rastered, it mainly conveys useful information about the data it contains.

Filterable.

Type:: str or BandType

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

class GenericBand(*args, **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 EarthOne catalog generic band. If you instead want to retrieve an existing catalog generic band use Band.get(), or if you’re not sure use GenericBand.get_or_create(). You can also use Band.search(). Also see the example for save().

Parameters:

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_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, and state), any attribute listed below can also be used as a keyword argument. Also see ATTRIBUTES.

Methods:

`delete`(id[, client])	Delete the catalog object with the given `id`.
`exists`(id[, client, headers])	Checks if an object exists in the EarthOne catalog.
`get`(id[, client, request_params, headers])	Get an existing object from the EarthOne catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the EarthOne catalog.
`get_or_create`(id[, client, request_params, ...])	Get an existing object from the EarthOne catalog or create a new object.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`reload`([request_params, headers])	Reload all attributes from the EarthOne catalog.
`save`([request_params, headers])	Saves this object to the EarthOne catalog.
`search`([client, request_params, headers])	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.

Attributes:

`ATTRIBUTES`
`band_index`	The 0-based index into the source data to access this band.
`colormap`	A custom colormap for this band.
`colormap_name`	Name of a predefined colormap for display purposes.
`created`	The point in time this object was created.
`data_range`	The range of pixel values stored in the band.
`data_type`	The data type for pixel values in this band.
`derived_params`	Derived Band Parameters Attribute.
`description`	A description with further details on the band.
`display_range`	The range of pixel values for display purposes.
`extra_properties`	A dictionary of up to 50 key/value pairs.
`file_index`	The 0-based index into the list of source files.
`id`	An optional unique identifier for this object.
`is_modified`	Whether any attributes were changed (see `state`).
`jpx_layer_index`	The 0-based layer index if the source data is JPEG2000 with layers.
`modified`	The point in time this object was last modified.
`name`	The name of the catalog object.
`nodata`	A value representing missing data in a pixel in this band.
`physical_range`	A physical range that pixel values map to.
`physical_range_unit`	Unit of the physical range.
`processing_levels`	An attribute that contains properties (key/value pairs).
`product`	The product instance this catalog object belongs to.
`product_id`	The id of the product this catalog object belongs to.
`resolution`	The spatial resolution of this band.
`sort_order`	A number defining the default sort order for bands within a product.
`state`	The state of this catalog object.
`tags`	A list of up to 32 tags, each up to 1000 bytes long.
`type`	The type of this band, directly corresponding to a `Band` derived class.
`vendor_band_name`	The name of the band in the source file.
`vendor_order`	A number defining the ordering of bands within a product as defined by the data vendor.

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 EarthOne catalog. The get_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') 

There is also an instance delete method that can be used to delete an object. It accepts no parameters and does not return anything. Once deleted, you cannot use the catalog object and should release any references.

classmethod exists(id, client=None, headers=None)

Checks if an object exists in the EarthOne catalog.

Parameters:

id (str) – The id of the object.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

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

Return type:

bool

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get(id, client=None, request_params=None, headers=None)

Get an existing object from the EarthOne catalog.

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

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

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

The object you requested, or None if an object with the given id does not exist in the EarthOne 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, request_params=None, headers=None)

Get existing objects from the EarthOne catalog.

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

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

Parameters:

ids (list(str)) – A list of identifiers for the objects you are requesting.
ignore_missing (bool, optional) – Whether to raise a NotFoundError exception if any of the requested objects are not found in the EarthOne catalog. False by default which raises the exception.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the EarthOne catalog and ignore_missing is False.
ClientError or ServerError – Spurious exception that can occur during a network request.

classmethod get_or_create(id, client=None, request_params=None, headers=None, **kwargs)

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

If the EarthOne 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 EarthOne 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 EarthOne catalog object is not found, it will be created and the state will be UNSAVED. Also see the example for save().

Parameters:

id (str) – The id of the object you are requesting.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the EarthOne catalog. The get_default_client() will be used if not set.
kwargs (dict, optional) – With the exception of readonly attributes (created, modified), any attribute of a catalog object can be set as a keyword argument (Also see ATTRIBUTES).

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

classmethod make_valid_name(name)

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

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

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

Parameters:: name (str) – A name for a Band or Image that may contain invalid characters.
Returns:: A name for a Band or Image that does not contain any invalid characters.
Return type:: str

Example

>>> from earthdaily.earthone.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(request_params=None, headers=None)

Reload all attributes from the EarthOne catalog.

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

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

Raises:

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.

save(request_params=None, headers=None)

Saves this object to the EarthOne catalog.

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

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

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

Parameters:

request_params (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 EarthOne catalog even though no attributes were modified.
headers (dict, optional) – A dictionary of header keys and values to be sent with the request.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the EarthOne 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.

classmethod search(client=None, request_params=None, headers=None)

A search query for all bands.

Returns an instance of the Search class configured for searching bands. Call this on the Band base class to search all types of bands or classes SpectralBand, MicrowaveBand, MaskBand, ClassBand and GenericBand to search only a specific type of band.

Parameters:: client (CatalogClient) – A CatalogClient instance to use for requests to the EarthOne catalog.
Returns:: An instance of the Search class
Return type:: Search

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

modified_only (bool, optional) – Whether only modified attributes should be serialized. False by default. If set to True, only those attributes that were modified since the last time the catalog object was retrieved or saved will be included.
jsonapi_format (bool, optional) – Whether to use the data element for catalog objects. False by default. When set to False, the serialized data will directly contain the attributes of the catalog object. If set to True, the serialized data will follow the exact JSONAPI with a top-level data element which contains id, type, and attributes. The latter will contain the attributes of the catalog object.

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

AttributeValidationError – If one or more of the attributes being updated are immutable.
AttributeError – If one or more of the attributes are not part of this catalog object.
DeletedObjectError – If this catalog object was deleted.

ATTRIBUTES = ('physical_range', 'physical_range_unit', 'colormap_name', 'colormap', 'description', 'type', 'sort_order', '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', 'extra_properties', 'tags', 'created', 'modified')

band_index

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

Type:: int

colormap

A custom colormap for this band.

A list of tuples, where each nested tuple is a 4-tuple of RGBA values to map pixels whose value is the index of the list. E.g. the colormap [(100, 20, 200, 255)] would map pixels whose value is 0 in the original band to the RGBA color defined by (100, 20, 200, 255). The number of 4-tuples provided can be up to the maximum of this band’s data range. Omitted values will map to black by default.

Type:: list(tuple), optional

colormap_name

Name of a predefined colormap for display purposes.

The colormap is applied when this band is rastered by itself in PNG or TIFF format, including in UIs where imagery is visualized.

Type:: str or Colormap, optional

created

The point in time this object was created.

Filterable, sortable.

Type:: datetime, readonly

data_range

The range of pixel values stored in the band.

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

Type:: tuple(float, float)

data_type

The data type for pixel values in this band.

Type:: str or DataType

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 dictionary must be strings, and the values of this dictionary can be strings or numbers. This allows for more structured custom metadata to be associated with objects.

Type:: dict, optional

file_index

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

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

Type:: int, optional

id

An optional unique identifier for this object.

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

Type:: str, immutable

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

jpx_layer_index

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

Defaults to 0.

Type:: int, optional

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

name

The name of the catalog object.

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

Sortable.

Type:: str, immutable

nodata

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

Type:: float, optional

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 of ProcessingStepAttribute 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

resolution

The spatial resolution of this band.

Filterable, sortable.

Type:: Resolution, optional

sort_order

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

If not set for newly created bands, this will default to the current maximum sort order + 1 in the product.

Sortable.

Type:: int, optional

property state

The state of this catalog object.

Type:: DocumentState

tags

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

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

Filterable.

Type:: list, optional

type

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

The derived classes are SpectralBand, MicrowaveBand, MaskBand, ClassBand, and GenericBand. The type never needs to be set explicitly, this attribute is implied by the derived class used. The type of a band does not necessarily affect how it is rastered, it mainly conveys useful information about the data it contains.

Filterable.

Type:: str or BandType

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

class BandCollection(iterable=None, item_type=None)[source]

Methods:

`append`(x)	Append x to the end of this `Collection`.
`extend`(x)	Extend this `Collection` by appending elements from the iterable.
`filter`(predicate)	Returns a `Collection` filtered by predicate.
`groupby`(*predicates)	Groups items by predicates.
`map`(f)	Returns a `Collection` of `f` applied to each item.
`sort`(field[, ascending])	Returns a `Collection`, sorted by the given field and direction.
`sorted`(predicates, *reverse)	Returns a `Collection`, sorted by predicates in ascending order.

Attributes:

each

Any operations chained onto each (attribute access, item access, and calls) are applied to each item in the Collection.

append(x)

Append x to the end of this Collection.

The type of the item must match the type of the collection.

Parameters:: x (Any) – Add an item to the collection

extend(x)

Extend this Collection by appending elements from the iterable.

The type of the items in the list must all match the type of the collection.

Parameters:: x (List[Any]) – Extend a collection with the items from the list.

filter(predicate)

Returns a Collection filtered by predicate.

Predicate can either be a callable or an Expression from Properties.

If the predicate is a callable, filter() will return all items for which predicate(item) is True.

If the predicate is an Expression, filter() will return all items for which predicate.evaluate(item) is True.

Parameters:: predicate (callable or Expression) – Either a callable or a Properties Expression which is called or evaluated for each item in the list.
Returns:: A new collection with only those items for which the predicate returned or evaluated to True.
Return type:: Collection

groupby(*predicates)

Groups items by predicates.

Groups items by predicates and yields tuple of (group, items) for each group, where items is a Collection.

Each predicate can be a key function, or a string of dot-chained attributes to use as sort keys.

Parameters:: predicates (callable or str) – Any positional arguments are predicates. If the predicate is a string, it denotes an attribute for each element, potentially with levels separated by a dot. If the predicate is a callable, it must return the value to sort by for each given element.
Yields:: Tuple[str, Collection] – A tuple of (group, Collection) for each group.

Examples

>>> import collections
>>> FooBar = collections.namedtuple("FooBar", ["foo", "bar"])
>>> c = Collection([FooBar("a", True), FooBar("b", False), FooBar("a", False)])

>>> for group, items in c.groupby("foo"):
...     print(group)
...     print(items)
a
Collection([FooBar(foo='a', bar=True), FooBar(foo='a', bar=False)])
b
Collection([FooBar(foo='b', bar=False)])
>>> for group, items in c.groupby("bar"):
...     print(group)
...     print(items)
False
Collection([FooBar(foo='b', bar=False), FooBar(foo='a', bar=False)])
True
Collection([FooBar(foo='a', bar=True)])

map(f)

Returns a Collection of f applied to each item.

Parameters:: f (callable) – Apply function f to each element of the collection and return the result as a collection.
Returns:: A collection with the results of the function f applied to each element of the original collection.
Return type:: Collection

sort(field, ascending=True)

Returns a Collection, sorted by the given field and direction.

Parameters:

field (str) – The name of the field to sort by
ascending (bool) – Sorts results in ascending order if True (the default), and in descending order if False.

Returns:

The sorted collection.

Return type:

Collection

Example

>>> from earthdaily.earthone.catalog import Product
>>> collection = Product.search().collect() 
>>> sorted_collection = collection.sort("created", ascending=False) 
>>> sorted_collection 

sorted(*predicates, **reverse)

Returns a Collection, sorted by predicates in ascending order.

Each predicate can be a key function, or a string of dot-chained attributes to use as sort keys. The reverse flag returns results in descending order.

Parameters:

predicates (callable or str) – Any positional arguments are predicates. If the predicate is a string, it denotes an attribute for each element, potentially with levels separated by a dot. If the predicate is a callable, it must return the value to sort by for each given element.
reverse (bool) – The sort is ascending by default, by setting reverse to True, the sort will be descending.

Returns:

The sorted collection.

Return type:

Collection

Examples

>>> import collections
>>> FooBar = collections.namedtuple("FooBar", ["foo", "bar"])
>>> X = collections.namedtuple("X", "x")
>>> c = Collection([FooBar(1, X("one")), FooBar(2, X("two")), FooBar(3, X("three"))])

>>> c.sorted("foo")
Collection([FooBar(foo=1, bar=X(x='one')), FooBar(foo=2, bar=X(x='two')), FooBar(foo=3, bar=X(x='three'))])
>>> c.sorted("bar.x")
Collection([FooBar(foo=1, bar=X(x='one')), FooBar(foo=3, bar=X(x='three')), FooBar(foo=2, bar=X(x='two'))])

property each

Any operations chained onto each (attribute access, item access, and calls) are applied to each item in the Collection.

Yields:: Any – The result of an item with all operations following each applied to it.

Notes

Add combine() at the end of the operations chain to combine the results into a list by default, or any container type passed into combine()
Use pipe(f, *args, **kwargs) to yield f(x, *args, **kwargs) for each item x yielded by the preceeding operations chain

Examples

>>> c = Collection(["one", "two", "three", "four"])
>>> for x in c.each.capitalize():
...     print(x)
One
Two
Three
Four
>>> c.each.capitalize()[:2]
'On'
'Tw'
'Th'
'Fo'
>>> c.each.capitalize().pipe(len)
3
3
5
4
>>> list(c.each.capitalize().pipe(len).combine(set))
[3, 4, 5]