Image

`Image`	An image with raster data.
`ImageCollection`	Holds Images, with methods for loading their data.
`ImageUpload`	The status object returned when you upload an image using `upload()` or `upload_ndarray()`.

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

An image with raster data.

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

Parameters:

client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. The get_default_client() will be used if not set.
kwargs (dict) – 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.

delete()

Delete this catalog object from the Descartes Labs catalog.

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

Raises:

DeletedObjectError – If this catalog object was already deleted.
UnsavedObjectError – If this catalog object is being deleted without having been saved.
ClientError or ServerError – Spurious exception that can occur during a network request.

Methods:

`coverage`(geom)	The fraction of a geometry-like object covered by this Image's geometry.
`delete`(id[, client])	Delete the catalog object with the given `id`.
`download`(bands[, geocontext, crs, ...])	Save bands from this image as a GeoTIFF, PNG, or JPEG, writing to a path.
`exists`(id[, client])	Checks if an object exists in the Descartes Labs catalog.
`get`(id[, client, request_params])	Get an existing object from the Descartes Labs catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the Descartes Labs catalog.
`get_or_create`(id[, client])	Get an existing object from the Descartes Labs catalog or create a new object.
`image_uploads`()	A search query for all uploads for this image created by this user.
`make_valid_name`(name)	Replace invalid characters in the given name and return a valid name.
`ndarray`(bands[, geocontext, crs, ...])	Load bands from this image as an ndarray, optionally masking invalid data.
`reload`([request_params])	Reload all attributes from the Descartes Labs catalog.
`save`([request_params])	Saves this object to the Descartes Labs catalog.
`scaling_parameters`(bands[, ...])	Computes fully defaulted scaling parameters and output data_type from provided specifications.
`search`([client, request_params])	A search query for all images.
`serialize`([modified_only, jsonapi_format])	Serialize the catalog object into json.
`update`([ignore_errors])	Update multiple attributes at once using the given keyword arguments.
`upload`(files[, upload_options, overwrite])	Uploads imagery from a file (or files).
`upload_ndarray`(ndarray[, upload_options, ...])	Uploads imagery from an ndarray to be ingested as an Image.

Attributes:

`ATTRIBUTES`
`SUPPORTED_DATATYPES`
`acquired`	Timestamp when the image was captured by its sensor or created.
`acquired_end`	Timestamp when the image capture by its sensor was completed.
`alt_cloud_fraction`	Fraction of pixels which are obscured by clouds.
`area`	Surface area the image covers.
`azimuth_angle`	Sensor azimuth angle in degrees.
`bits_per_pixel`	Average bits of data per pixel per band.
`bright_fraction`	Fraction of the image that has reflectance greater than .4 in the blue band.
`cloud_fraction`	Fraction of pixels which are obscured by clouds.
`created`	The point in time this object was created.
`cs_code`	The coordinate reference system used by the image as an EPSG or ESRI code.
`date`
`extra_properties`	A dictionary of up to 50 key/value pairs.
`files`	The list of files holding data for this image.
`fill_fraction`	Fraction of this image which has data.
`geocontext`	A geocontext for loading this Image's original, unwarped data.
`geometry`	Geometry representing the image coverage.
`geotrans`	GDAL-style geotransform matrix.
`id`	An optional unique identifier for this object.
`incidence_angle`	Sensor incidence angle in degrees.
`is_modified`	Whether any attributes were changed (see `state`).
`modified`	The point in time this object was last modified.
`name`	The name of the catalog object.
`preview_file`	A GCS URL with a georeferenced image.
`preview_url`	An external (http) URL to a preview image.
`processing_pipeline_id`	Identifier for the pipeline that processed this image from raw data.
`product`	The product instance this catalog object belongs to.
`product_id`	The id of the product this catalog object belongs to.
`projection`	The spatial reference system used by the image.
`provider_id`	Id that uniquely ties this image to an entity as understood by the data provider.
`provider_url`	An external (http) URL that has more details about the image
`published`	Timestamp when the data provider published this image.
`reflectance_scale`	Scale factors converting TOA radiances to TOA reflectances.
`roll_angle`	Applicable only to Landsat 8, roll angle in degrees.
`satellite_id`	Id of the capturing satellite/sensor among a constellation of many satellites.
`solar_azimuth_angle`	Solar azimuth angle at capture time.
`solar_elevation_angle`	Solar elevation angle at capture time.
`state`	The state of this catalog object.
`storage_state`	Storage state of the image.
`tags`	A list of up to 32 tags, each up to 1000 bytes long.
`view_angle`	Sensor view angle in degrees.
`x_pixels`	X dimension of the image in pixels.
`y_pixels`	Y dimension of the image in pixels.

coverage(geom)[source]

The fraction of a geometry-like object covered by this Image’s geometry.

Parameters:: geom (GeoJSON-like dict, GeoContext, or object with __geo_interface__) – Geometry to which to compare this Image’s geometry
Returns:: coverage – The fraction of geom’s area that overlaps with this Image, between 0 and 1.
Return type:: float

Example

>>> import descarteslabs as dl
>>> image = dl.catalog.Image.get("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")  
>>> image.coverage(image.geometry.buffer(1))  
0.258370644415335

classmethod delete(id, client=None)

Delete the catalog object with the given id.

Parameters:

id (str) – The id of the object to be deleted.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog. 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') 

download(bands, geocontext=None, crs=None, resolution=None, all_touched=None, dest=None, format=DownloadFileFormat.TIF, resampler=ResampleAlgorithm.NEAR, processing_level=None, scaling=None, data_type=None, nodata=None, progress=None)[source]

Save bands from this image as a GeoTIFF, PNG, or JPEG, writing to a path.

Parameters:

bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue"), or a sequence of band names (["red", "green", "blue"]). Names must be keys in self.properties.bands.
geocontext (GeoContext, default None) – A GeoContext to use when loading this image. If None then use the default context for the image.
crs (str, default None) – if not None, update the gecontext with this value to set the output CRS.
resolution (float, default None) – if not None, update the geocontext with this value to set the output resolution in the units native to the specified or defaulted output CRS.
all_touched (float, default None) – if not None, update the geocontext with this value to control rastering behavior.
dest (str or path-like object, default None) –
Where to write the image file.
- If None (default), it’s written to an image file of the given format in the current directory, named by the image’s ID and requested bands, like "sentinel-2:L1C:2018-08-10_10TGK_68_S2A_v1-red-green-blue.tif"
- If a string or path-like object, it’s written to that path.
  
  Any file already existing at that path will be overwritten.
  
  Any intermediate directories will be created if they don’t exist.
  
  Note that path-like objects (such as pathlib.Path) are only supported in Python 3.6 or later.
format (DownloadFileFormat, default DownloadFileFormat.TIF) – Output file format to use If a str or path-like object is given as dest, format is ignored and determined from the extension on the path (one of “.tif”, “.png”, or “.jpg”).
resampler (ResampleAlgorithm, default ResampleAlgorithm.NEAR) – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or SRS.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None, str, list, dict) – Band scaling specification. Please see scaling_parameters() for a full description of this parameter.
data_type (None, str) – Output data type. Please see scaling_parameters() for a full description of this parameter.
nodata (None, number) – NODATA value for a geotiff file. Will be assigned to any masked pixels.
progress (None, bool) – Controls display of a progress bar.

Returns:

path – If dest is None or a path, the path where the image file was written is returned. If dest is file-like, nothing is returned.

Return type:

str or None

Example

>>> import descarteslabs as dl
>>> image = dl.catalog.Image.get("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")  
>>> image.download("red green blue", resolution=120.)  
"landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1_red-green-blue.tif"
>>> import os
>>> os.listdir(".")  
["landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1_red-green-blue.tif"]
>>> image.download(
...     "nir swir1",
...     "rasters/{geocontext.resolution}-{image_id}.jpg".format(geocontext=image.geocontext, image_id=image.id)
... )  
"rasters/15-landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1.tif"

Raises:

ValueError – If requested bands are unavailable. If band names are not given or are invalid. If the requested bands have incompatible dtypes. If format is invalid, or the path has an invalid extension.
NotFoundError – If a image’s ID cannot be found in the Descartes Labs catalog
BadRequestError – If the Descartes Labs Platform is given invalid parameters

classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters:

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

Returns:

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

Return type:

bool

Raises:

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

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

Get an existing object from the Descartes Labs catalog.

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

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

Parameters:

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

Returns:

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

Return type:

CatalogObject or None

Raises:

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

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

Get existing objects from the Descartes Labs catalog.

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

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

Parameters:

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

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the Descartes Labs 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, **kwargs)

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

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

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

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

Parameters:

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

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

image_uploads()[source]

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

Returns:: A Search instance configured to find all uploads for this image.
Return type:: Search

classmethod make_valid_name(name)

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

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

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

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

Example

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

ndarray(bands, geocontext=None, crs=None, resolution=None, all_touched=None, mask_nodata=True, mask_alpha=None, bands_axis=0, raster_info=False, resampler=ResampleAlgorithm.NEAR, processing_level=None, scaling=None, data_type=None, progress=None)[source]

Load bands from this image as an ndarray, optionally masking invalid data.

If the selected bands have different data types the resulting ndarray has the most general of those data types. This table defines which data types can be cast to which more general data types:

Byte to: UInt16, UInt32, Int16, Int32, Float32, Float64
UInt16 to: UInt32, Int32, Float32, Float64
UInt32 to: Float64
Int16 to: Int32, Float32, Float64
Int32 to: Float32, Float64
Float32 to: Float64
Float64 to: No possible casts

Parameters:

bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue"), or a sequence of band names (["red", "green", "blue"]). Names must be keys in self.properties.bands. If the alpha band is requested, it must be last in the list to reduce rasterization errors.
geocontext (GeoContext, default None) – A GeoContext to use when loading this Image. If None then the default geocontext of the image will be used.
crs (str, default None) – if not None, update the gecontext with this value to set the output CRS.
resolution (float, default None) – if not None, update the geocontext with this value to set the output resolution in the units native to the specified or defaulted output CRS.
all_touched (float, default None) – if not None, update the geocontext with this value to control rastering behavior.
mask_nodata (bool, default True) – Whether to mask out values in each band that equal that band’s nodata sentinel value.
mask_alpha (bool or str or None, default None) – Whether to mask pixels in all bands where the alpha band of the image is 0. Provide a string to use an alternate band name for masking. If the alpha band is available and mask_alpha is None, mask_alpha is set to True. If not, mask_alpha is set to False.
bands_axis (int, default 0) –
Axis along which bands should be located in the returned array. If 0, the array will have shape (band, y, x), if -1, it will have shape (y, x, band).

It’s usually easier to work with bands as the outermost axis, but when working with large arrays, or with many arrays concatenated together, NumPy operations aggregating each xy point across bands can be slightly faster with bands as the innermost axis.
raster_info (bool, default False) – Whether to also return a dict of information about the rasterization of the image, including the coordinate system WKT and geotransform matrix. Generally only useful if you plan to upload data derived from this image back to the Descartes Labs catalog, or use it with GDAL.
resampler (ResampleAlgorithm, default ResampleAlgorithm.NEAR) – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or CRS.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None, str, list, dict) – Band scaling specification. Please see scaling_parameters() for a full description of this parameter.
data_type (None, str) – Output data type. Please see scaling_parameters() for a full description of this parameter.
progress (None, bool) – Controls display of a progress bar.

Returns:

arr (ndarray) – Returned array’s shape will be (band, y, x) if bands_axis is 0, (y, x, band) if bands_axis is -1. If mask_nodata or mask_alpha is True, arr will be a masked array. The data type (“dtype”) of the array is the most general of the data types among the bands being rastered.
raster_info (dict) – If raster_info=True, a raster information dict is also returned.

Example

>>> import descarteslabs as dl
>>> image = dl.catalog.Image.get("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")  
>>> arr = image.ndarray("red green blue", resolution=120.)  
>>> type(arr)  
<class 'numpy.ma.core.MaskedArray'>
>>> arr.shape  
(3, 1995, 1962)
>>> red_band = arr[0]  

Raises:

ValueError – If requested bands are unavailable. If band names are not given or are invalid. If the requested bands have incompatible dtypes.
NotFoundError – If a Image’s ID cannot be found in the Descartes Labs catalog
BadRequestError – If the Descartes Labs Platform is given invalid parameters

reload(request_params=None)

Reload all attributes from the Descartes Labs catalog.

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

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

Raises:

ValueError – If the catalog object is not in the SAVED state.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.

Example

>>> from descarteslabs.catalog import Product
>>> p = Product(id="my_org_id:my_product_id")
>>> # Some time elapses and a concurrent change was made
>>> p.state 
<DocumentState.SAVED: 'saved'>
>>> p.reload() 
>>> # But once you make changes, you cannot use this method any more
>>> p.name = "My name has changed"
>>> p.reload() 
Traceback (most recent call last):
  ...
ValueError: Product instance with id my_org_id:my_product_id has not been saved
>>> # But you can revert
>>> p = Product.get(p.id) 
>>> p.state 
<DocumentState.SAVED: 'saved'>

save(request_params=None)

Saves this object to the Descartes Labs catalog.

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

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

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no 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 Descartes Labs catalog even though no attributes were modified.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the Descartes Labs catalog.
BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.

Example

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

scaling_parameters(bands, processing_level=None, scaling=None, data_type=None)[source]

Computes fully defaulted scaling parameters and output data_type from provided specifications.

This method makes accessible the scales and data_type parameters which will be generated and passed to the Raster API by methods such as ndarray() and download(). It is provided as a convenience to the user to aid in understanding how the scaling and data_type parameters will be handled by those methods. It would not usually be used in a normal workflow.

Parameters:

bands (list) – List of bands to be scaled.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None or str or list or dict, default None) – Supplied scaling specification, see below.
data_type (None or str, default None) – Result data type desired, as a standard data type string (e.g. "Byte", "Uint16", or "Float64"). If not specified, will be deduced from the scaling specification. Typically this is left unset and the appropriate type will be determined automatically.

Returns:

scales (list(tuple)) – The fully specified scaling parameter, compatible with the Raster API and the output data type.
data_type (str) – The result data type as a standard GDAL type string.

Raises:

ValueError – If any invalid or incompatible value is passed to any of the three parameters.

Scaling is determined on a band-by-band basis, incorporating the user provided specification, the output data_type, and properties for the band, such as the band type, the band data type, and the default_range, data_range, and physical_range properties. Ultimately the scaling for each band will be resolved to either None or a tuple of numeric values of length 0, 2, or 4, as accepted by the Raster API. The result is a list (with length equal to the number of bands) of one of these values, or may be a None value which is just a shorthand equivalent for a list of None values.

A None indicates that no scaling should be performed.

A 0-tuple () indicates that the band data should be automatically scaled from the minimum and maximum values present in the image data to the display range 0-255.

A 2-tuple (input-min, input-max) indicates that the band data should be scaled from the specified input range to the display range of 0-255.

A 4-tuple (input-min, input-max, output-min, output-max) indicates that the band data should be scaled from the input range to the output range.

In all cases, the scaling will be performed as a multiply and add, and the resulting values are only clipped as necessary to fit in the output data type. As such, if the input and output ranges are the same, it is effectively a no-op equivalent to None.

The support for scaling parameters in the Catalog API includes the concept of an automated scaling mode. The four supported modes are as follows.

"raw":: Equivalent to a None, the data should not be scaled.
"auto":: Equivalent to a 0-tuple, the data should be scaled by the Raster service so that the actual range of data in the input is scaled up to the full display range (0-255). It is not possible to determine the bounds of this input range in the client as the actual band data is not accessible.
"display":: The data should be scaled from any specified input bounds, defaulting to the default_range property for the band, to the output range, defaulting to 0-255.
"physical":: The data should be scaled from the input range, defaulting to the data_range property for the band, to the output range, defaulting to the physical_range property for the band.

The mode may be explicitly specified, or it may be determined implicitly from other characteristics such as the length and contents of the tuples for each band, or from the output data_type if this is explicitly specified (e.g. "Byte" implies display mode, "Float64" implies physical mode).

If it is not possible to infer the mode, and a mode is required in order to fully determine the results of this method, an error will be raised. It is also an error to explicitly specify more than one mode, with several exceptions: auto and display mode are compatible, while a raw display mode for a band which is of type “mask” or type “class” does not conflict with any other mode specification.

Normally the data_type parameter is not provided by the user, and is instead determined from the mode as follows.

"raw":: The data type that best matches the data types of all the bands, preserving the precision and range of the original data.
"auto" and "display":: "Byte"
"physical":: "Float64"

The scaling parameter passed to this method can be any of the following:

None:: No scaling for all bands. Equivalent to [None, ...].
str:: Any of the four supported automatic modes as described above.
list or Iterable:: A list or similar iterable must contain a number of elements equal to the number of bands specified. Each element must either be a None, a 0-, 2-, or 4-tuple, or one of the above four automatic mode strings. The elements of each tuple must either be a numeric value or a string containing a valid numerical string followed by a “%” character. The latter will be interpreted as a percentage of the appropriate range (e.g. default_range, data_range, or physical_range) according to the mode. For example, a tuple of ("25%", "75%") with a default_range of [0, 4000] will yield (1000, 3000).
dict or Mapping:: A dictionary or similar mapping with keys corresponding to band names and values as accepted as elements for each band as with a list described above. Each band name is used to lookup a value in the mapping. If none is found, and the band is not of type “mask” or “class”, then the special key "default_" is looked up in the mapping if it exists. Otherwise a value of None will be used for the band. This is strictly a convenience for constructing a list of scale values, one for each band, but can be useful if a single general-purpose mapping is defined for all possible or relevant bands and then reused across many calls to the different methods in the Catalog API which accept a scaling parameter.

See also

Catalog Guide : This contains many examples of the use of the scaling and data_type parameters.

classmethod search(client=None, request_params=None)[source]

A search query for all images.

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

Parameters:: client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog.
Returns:: An instance of the ImageSearch class
Return type:: ImageSearch

Example

>>> from descarteslabs.catalog import Image
>>> search = Image.search().limit(10)
>>> for result in search: 
...     print(result.name) 

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

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

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

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

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

Uploads imagery from a file (or files).

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

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

Parameters:

files (str or io.IOBase or iterable of same) – File or files to be uploaded. Can be string with path to the file in the local filesystem, or an opened file (io.IOBase), or an iterable of either of these when multiple files make up the image.
upload_options (ImageUploadOptions, optional) – Control of the upload process.
overwrite (bool, optional) – If True, then permit overwriting of an existing image with the same id in the catalog. Defaults to False. Note that in all cases, the image object must have a state of UNSAVED. USE WITH CAUTION: This can cause data cache inconsistencies in the platform, and should only be used for infrequent needs to update the image file contents. You can expect inconsistencies to endure for a period afterwards.

Returns:

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

Return type:

ImageUpload

Raises:

ValueError – If any improper arguments are supplied.
DeletedObjectError – If this image was deleted.

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

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

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

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

Parameters:

ndarray (np.array, Iterable(np.array)) – A numpy array or list of numpy arrays with image data, either with 2 dimensions of shape (x, y) for a single band or with 3 dimensions of shape (band, x, y) for any number of bands. If providing a 3d array the first dimension must index the bands. The dtype of the array must also be one of the following: [uint8, int8, uint16, int16, uint32, int32, float32, float64]
upload_options (ImageUploadOptions, optional) – Control of the upload process.
raster_meta (dict, optional) – Metadata returned from the Raster.ndarray() request which generated the initial data for the ndarray being uploaded. Specifying geotrans and one of the spatial reference attributes (cs_code or projection) is unnecessary in this case but will take precedence over the value in raster_meta.
overviews (list(int), optional) – Overview resolution magnification factors e.g. [2, 4] would make two overviews at 2x and 4x the native resolution. Maximum number of overviews allowed is 16. Can also be set in the upload_options parameter.
overview_resampler (ResampleAlgorithm, optional) – Resampler algorithm to use when building overviews. Controls how pixels are combined to make lower res pixels in overviews. Can also be set in the upload_options parameter.
overwrite (bool, optional) – If True, then permit overwriting of an existing image with the same id in the catalog. Defaults to False. Note that in all cases, the image object must have a state of UNSAVED. USE WITH CAUTION: This can cause data cache inconsistencies in the platform, and should only be used for infrequent needs to update the image file contents. You can expect inconsistencies to endure for a period afterwards.

Raises:

ValueError – If any improper arguments are supplied.
DeletedObjectError – If this image was deleted.

Returns:

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

Return type:

ImageUpload

ATTRIBUTES = ('geometry', 'cs_code', 'projection', 'geotrans', 'x_pixels', 'y_pixels', 'acquired', 'acquired_end', 'published', 'storage_state', 'files', 'area', 'azimuth_angle', 'bits_per_pixel', 'bright_fraction', 'brightness_temperature_k1_k2', 'c6s_dlsr', 'cloud_fraction', 'confidence_dlsr', 'alt_cloud_fraction', 'processing_pipeline_id', 'fill_fraction', 'incidence_angle', 'radiance_gain_bias', 'reflectance_gain_bias', 'reflectance_scale', 'roll_angle', 'solar_azimuth_angle', 'solar_elevation_angle', 'temperature_gain_bias', 'view_angle', 'satellite_id', 'provider_id', 'provider_url', 'preview_url', 'preview_file', 'id', 'name', 'product_id', 'product', 'extra_properties', 'tags', 'created', 'modified')

SUPPORTED_DATATYPES = ('uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64')

acquired

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

Filterable, sortable.

Type:: str or datetime

acquired_end

Timestamp when the image capture by its sensor was completed.

Filterable, sortable.

Type:: str or datetime, optional

alt_cloud_fraction

Fraction of pixels which are obscured by clouds.

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

Filterable, sortable.

Type:: float, optional

area

Surface area the image covers.

Filterable, sortable.

Type:: float, optional

azimuth_angle

Sensor azimuth angle in degrees.

Filterable, sortable.

Type:: float, optional

bits_per_pixel

Average bits of data per pixel per band.

Type:: list(float), optional

bright_fraction

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

Filterable, sortable.

Type:: float, optional

cloud_fraction

Fraction of pixels which are obscured by clouds.

Filterable, sortable.

Type:: float, optional

created

The point in time this object was created.

Filterable, sortable.

Type:: datetime, readonly

cs_code

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

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

Type:: str

property date

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

files

The list of files holding data for this image.

Type:: list(File)

fill_fraction

Fraction of this image which has data.

Filterable, sortable.

Type:: float, optional

property geocontext

A geocontext for loading this Image’s original, unwarped data.

These defaults are used:

resolution: resolution determined from the Image’s geotrans
crs: native CRS of the Image (often, a UTM CRS)
bounds: bounds determined from the Image’s geotrans, x_pixels and y_pixels
bounds_crs: native CRS of the Image
align_pixels: False, to prevent interpolation snapping pixels to a new grid
geometry: None

Note

Using this GeoContext will only return original, unwarped data if the Image is axis-aligned (“north-up”) within the CRS. If its geotrans applies a rotation, a warning will be raised. In that case, use Raster.ndarray or Raster.raster to retrieve original data. (The GeoContext paradigm requires bounds for consistency, which are inherently axis-aligned.)

Type:: AOI

geometry

Geometry representing the image coverage.

Filterable

(use ImageSearch.intersects to search based on geometry)

Type:: str or shapely.geometry.base.BaseGeometry

geotrans

GDAL-style geotransform matrix.

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

Type:: tuple of six float elements, optional if REMOTE

id

An optional unique identifier for this object.

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

Type:: str, immutable

incidence_angle

Sensor incidence angle in degrees.

Filterable, sortable.

Type:: float, optional

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

name

The name of the catalog object.

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

Sortable.

Type:: str, immutable

preview_file

A GCS URL with a georeferenced image.

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

Type:: str, optional

preview_url

An external (http) URL to a preview image.

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

Type:: str, optional

processing_pipeline_id

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

Filterable, sortable.

Type:: str, optional

product

The product instance this catalog object belongs to.

If given, it is used to retrieve the product_id.

Filterable.

Type:: Product, immutable

product_id

The id of the product this catalog object belongs to.

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

Filterable, sortable.

Type:: str, immutable

projection

The spatial reference system used by the image.

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

Type:: str

provider_id

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

Filterable, sortable.

Type:: str, optional

provider_url

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

Type:: str, optional

published

Timestamp when the data provider published this image.

Filterable, sortable.

Type:: str or datetime, optional

reflectance_scale

Scale factors converting TOA radiances to TOA reflectances.

Type:: list(float), optional

roll_angle

Applicable only to Landsat 8, roll angle in degrees.

Filterable, sortable.

Type:: float, optional

satellite_id

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

Filterable, sortable.

Type:: str, optional

solar_azimuth_angle

Solar azimuth angle at capture time.

Filterable, sortable.

Type:: float, optional

solar_elevation_angle

Solar elevation angle at capture time.

Filterable, sortable.

Type:: float, optional

property state

The state of this catalog object.

Type:: DocumentState

storage_state

Storage state of the image.

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

Filterable, sortable.

Type:: str or StorageState

tags

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

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

Filterable.

Type:: list, optional

view_angle

Sensor view angle in degrees.

Filterable, sortable.

Type:: float, optional

x_pixels

X dimension of the image in pixels.

Type:: int, optional if REMOTE

y_pixels

Y dimension of the image in pixels.

Type:: int, optional if REMOTE

class ImageCollection(iterable=None, geocontext=None)[source]

Holds Images, with methods for loading their data.

As a subclass of Collection, the filter, map, and groupby methods and each property simplify inspection and subselection of contained Images.

stack and mosaic rasterize all contained images into an ndarray using the a GeoContext.

Methods:

`append`(x)	Append x to the end of this `Collection`.
`download`(bands[, geocontext, crs, ...])	Download images as image files in parallel.
`download_mosaic`(bands[, geocontext, crs, ...])	Download all images as a single image file.
`extend`(x)	Extend this `Collection` by appending elements from the iterable.
`filter`(predicate)	Returns a `Collection` filtered by predicate.
`filter_coverage`(geom[, minimum_coverage])	Include only images overlapping with `geom` by some fraction.
`groupby`(*predicates)	Groups items by predicates.
`map`(f)	Returns a `Collection` of `f` applied to each item.
`mosaic`(bands[, geocontext, crs, resolution, ...])	Load bands from all images, combining them into a single 3D ndarray and optionally masking invalid data.
`scaling_parameters`(bands[, ...])	Computes fully defaulted scaling parameters and output data_type from provided specifications.
`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.
`stack`(bands[, geocontext, crs, resolution, ...])	Load bands from all images and stack them into a 4D ndarray, optionally masking invalid data.

Attributes:

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

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

download(bands, geocontext=None, crs=None, resolution=None, all_touched=None, dest=None, format=DownloadFileFormat.TIF, resampler=ResampleAlgorithm.NEAR, processing_level=None, scaling=None, data_type=None, progress=None, max_workers=None)[source]

Download images as image files in parallel.

Parameters:

bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue"), or a sequence of band names (["red", "green", "blue"]).
geocontext (GeoContext, default None) – A GeoContext to use when loading each image. If None then the default context of the collection will be used. If this is None, a ValueError is raised.
crs (str, default None) – if not None, update the gecontext with this value to set the output CRS.
resolution (float, default None) – if not None, update the geocontext with this value to set the output resolution in the units native to the specified or defaulted output CRS.
all_touched (float, default None) – if not None, update the geocontext with this value to control rastering behavior.
dest (str, path-like, or sequence of str or path-like, default None) –
Directory or sequence of paths to which to write the image files.

If None, the current directory is used.

If a directory, files within it will be named by their image IDs and the bands requested, like "sentinel-2:L1C:2018-08-10_10TGK_68_S2A_v1-red-green-blue.tif".

If a sequence of paths of the same length as the ImageCollection is given, each Image will be written to the corresponding path. This lets you use your own naming scheme, or even write images to multiple directories.

Any intermediate paths are created if they do not exist, for both a single directory and a sequence of paths.
format (DownloadFileFormat, default DownloadFileFormat.TIF) – Output file format to use. If dest is a sequence of paths, format is ignored and determined by the extension on each path.
resampler (ResampleAlgorithm, default ResampleAlgorithm.NEAR) – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or SRS.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None, str, list, dict) – Band scaling specification. Please see scaling_parameters() for a full description of this parameter.
data_type (None, str) – Output data type. Please see scaling_parameters() for a full description of this parameter.
progress (None, bool) – Controls display of a progress bar.
max_workers (int, default None) – Maximum number of threads to use to parallelize individual download calls to each Image. If None, it defaults to the number of processors on the machine, multiplied by 5. Note that unnecessary threads won’t be created if max_workers is greater than the number of Images in the ImageCollection.

Returns:

paths – A list of all the paths where files were written.

Return type:

Sequence[str]

Example

>>> import descarteslabs as dl
>>> tile = dl.common.geo.DLTile.from_key("256:0:75.0:15:-5:230")  
>>> product = dl.catalog.Product.get("landsat:LC08:PRE:TOAR")  
>>> images = product.images().intersects(tile).limit(5).collect()  
>>> images.download("red green blue", tile, "rasters")  
["rasters/landsat:LC08:PRE:TOAR:meta_LC80260322013108_v1-red-green-blue.tif",
 "rasters/landsat:LC08:PRE:TOAR:meta_LC80260322013124_v1-red-green-blue.tif",
 "rasters/landsat:LC08:PRE:TOAR:meta_LC80260322013140_v1-red-green-blue.tif",
 "rasters/landsat:LC08:PRE:TOAR:meta_LC80260322013156_v1-red-green-blue.tif",
 "rasters/landsat:LC08:PRE:TOAR:meta_LC80260322013172_v1-red-green-blue.tif"]
>>> # use explicit paths for a custom naming scheme:
>>> paths = [
...     "{tile.key}/l8-{image.date:%Y-%m-%d-%H:%m}.tif".format(tile=tile, image=image)
...     for image in images
... ]  
>>> images.download("nir red", tile, paths)  
["256:0:75.0:15:-5:230/l8-2013-04-18-16:04.tif",
 "256:0:75.0:15:-5:230/l8-2013-05-04-16:05.tif",
 "256:0:75.0:15:-5:230/l8-2013-05-20-16:05.tif",
 "256:0:75.0:15:-5:230/l8-2013-06-05-16:06.tif",
 "256:0:75.0:15:-5:230/l8-2013-06-21-16:06.tif"]

Raises:

RuntimeError – If the paths given are not all unique. If there is an error generating default filenames.
ValueError – If requested bands are unavailable, or band names are not given or are invalid. If not all required parameters are specified in the GeoContext. If the ImageCollection is empty. If dest is a sequence not equal in length to the ImageCollection. If format is invalid, or a path has an invalid extension.
TypeError – If dest is not a string or a sequence type.
NotFoundError – If a Image’s ID cannot be found in the Descartes Labs catalog
BadRequestError – If the Descartes Labs Platform is given unrecognized parameters

download_mosaic(bands, geocontext=None, crs=None, resolution=None, all_touched=None, dest=None, format=DownloadFileFormat.TIF, resampler=ResampleAlgorithm.NEAR, processing_level=None, scaling=None, data_type=None, mask_alpha=None, nodata=None, progress=None)[source]

Download all images as a single image file. Where multiple images overlap, only data from the image that comes last in the ImageCollection is used.

Parameters:

bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue"), or a sequence of band names (["red", "green", "blue"]).
geocontext (GeoContext, default None) – A GeoContext to use when loading each image. If None then the default context of the collection will be used. If this is None, a ValueError is raised.
crs (str, default None) – if not None, update the gecontext with this value to set the output CRS.
resolution (float, default None) – if not None, update the geocontext with this value to set the output resolution in the units native to the specified or defaulted output CRS.
all_touched (float, default None) – if not None, update the geocontext with this value to control rastering behavior.
dest (str or path-like object, default None) –
Where to write the image file.
- If None (default), it’s written to an image file of the given format in the current directory, named by the requested bands, like "mosaic-red-green-blue.tif"
- If a string or path-like object, it’s written to that path.
  
  Any file already existing at that path will be overwritten.
  
  Any intermediate directories will be created if they don’t exist.
  
  Note that path-like objects (such as pathlib.Path) are only supported in Python 3.6 or later.
format (DownloadFileFormat, default DownloadFileFormat.TIF) – Output file format to use. If a str or path-like object is given as dest, format is ignored and determined from the extension on the path (one of “.tif”, “.png”, or “.jpg”).
resampler (ResampleAlgorithm, default ResampleAlgorithm.NEAR) – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or SRS.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None, str, list, dict) – Band scaling specification. Please see scaling_parameters() for a full description of this parameter.
data_type (None, str) – Output data type. Please see scaling_parameters() for a full description of this parameter.
mask_alpha (bool or str or None, default None) – Whether to mask pixels in all bands where the alpha band of all images is 0. Provide a string to use an alternate band name for masking. If the alpha band is available for all images in the collection and mask_alpha is None, mask_alpha is set to True. If not, mask_alpha is set to False.
nodata (None, number) – NODATA value for a geotiff file. Will be assigned to any masked pixels.
progress (None, bool) – Controls display of a progress bar.

Returns:

path – If dest is a path or None, the path where the image file was written is returned. If dest is file-like, nothing is returned.

Return type:

str or None

Example

>>> import descarteslabs as dl
>>> tile = dl.common.geo.DLTile.from_key("256:0:75.0:15:-5:230")  
>>> product = dl.catalog.Product.get("landsat:LC08:PRE:TOAR")  
>>> images = product.images().intersects(tile).limit(5).collect()  
>>> images.download_mosaic("nir red", mask_alpha=False)  
'mosaic-nir-red.tif'
>>> images.download_mosaic("red green blue", dest="mosaics/{}.png".format(tile.key))  
'mosaics/256:0:75.0:15:-5:230.tif'

Raises:

ValueError – If requested bands are unavailable, or band names are not given or are invalid. If not all required parameters are specified in the GeoContext. If the ImageCollection is empty. If format is invalid, or the path has an invalid extension.
NotFoundError – If a Image’s ID cannot be found in the Descartes Labs catalog
BadRequestError – If the Descartes Labs Platform is given unrecognized parameters

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

filter_coverage(geom, minimum_coverage=1)[source]

Include only images overlapping with geom by some fraction.

See Image.coverage for getting coverage information for an image.

Parameters:

geom (GeoJSON-like dict, GeoContext, or object with __geo_interface__ # noqa: E501) – Geometry to which to compare each image’s geometry.
minimum_coverage (float) – Only include images that cover geom by at least this fraction.

Returns:

images

Return type:

ImageCollection

Example

>>> import descarteslabs as dl
>>> aoi_geometry = {
...    'type': 'Polygon',
...    'coordinates': [[[-95, 42],[-93, 42],[-93, 40],[-95, 41],[-95, 42]]]}
>>> product = dl.catalog.Product.get("landsat:LC08:PRE:TOAR")  
>>> images = product.images().intersects(aoi_geometry).limit(20).collect()  
>>> filtered_images = images.filter_coverage(images.geocontext, 0.01)  
>>> assert len(filtered_images) < len(images)  

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

mosaic(bands, geocontext=None, crs=None, resolution=None, all_touched=None, mask_nodata=True, mask_alpha=None, bands_axis=0, resampler=ResampleAlgorithm.NEAR, processing_level=None, scaling=None, data_type=None, progress=None, raster_info=False)[source]

Load bands from all images, combining them into a single 3D ndarray and optionally masking invalid data.

Where multiple images overlap, only data from the image that comes last in the ImageCollection is used.

If the selected bands and images have different data types the resulting ndarray has the most general of those data types. See Image.ndarray() for details on data type conversions.

Parameters:

bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue"), or a sequence of band names (["red", "green", "blue"]). If the alpha band is requested, it must be last in the list to reduce rasterization errors.
geocontext (GeoContext, default None) – A GeoContext to use when loading each image. If None then the default context of the collection will be used. If this is None, a ValueError is raised.
crs (str, default None) – if not None, update the gecontext with this value to set the output CRS.
resolution (float, default None) – if not None, update the geocontext with this value to set the output resolution in the units native to the specified or defaulted output CRS.
all_touched (float, default None) – if not None, update the geocontext with this value to control rastering behavior.
mask_nodata (bool, default True) – Whether to mask out values in each band that equal that band’s nodata sentinel value.
mask_alpha (bool or str or None, default None) – Whether to mask pixels in all bands where the alpha band of all images is 0. Provide a string to use an alternate band name for masking. If the alpha band is available for all images in the collection and mask_alpha is None, mask_alpha is set to True. If not, mask_alpha is set to False.
bands_axis (int, default 0) –
Axis along which bands should be located in the returned array. If 0, the array will have shape (band, y, x), if -1, it will have shape (y, x, band).

It’s usually easier to work with bands as the outermost axis, but when working with large arrays, or with many arrays concatenated together, NumPy operations aggregating each xy point across bands can be slightly faster with bands as the innermost axis.
raster_info (bool, default False) – Whether to also return a dict of information about the rasterization of the images, including the coordinate system WKT and geotransform matrix. Generally only useful if you plan to upload data derived from this image back to the Descartes Labs catalog, or use it with GDAL.
resampler (ResampleAlgorithm, default ResampleAlgorithm.NEAR) – Algorithm used to interpolate pixel values when scaling and transforming the image to its new resolution or SRS.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None, str, list, dict) – Band scaling specification. Please see scaling_parameters() for a full description of this parameter.
data_type (None, str) – Output data type. Please see scaling_parameters() for a full description of this parameter.
progress (None, bool) – Controls display of a progress bar.

Returns:

arr (ndarray) – Returned array’s shape will be (band, y, x) if bands_axis is 0, and (y, x, band) if bands_axis is -1. If mask_nodata or mask_alpha is True, arr will be a masked array. The data type (“dtype”) of the array is the most general of the data types among the images being rastered.
raster_info (dict) – If raster_info=True, a raster information dict is also returned.

Raises:

ValueError – If requested bands are unavailable, or band names are not given or are invalid. If not all required parameters are specified in the GeoContext. If the ImageCollection is empty.
NotFoundError – If a Image’s ID cannot be found in the Descartes Labs catalog
BadRequestError – If the Descartes Labs Platform is given unrecognized parameters

scaling_parameters(bands, processing_level=None, scaling=None, data_type=None)[source]

Computes fully defaulted scaling parameters and output data_type from provided specifications.

This method is provided as a convenience to the user to help with understanding how scaling and data_type parameters passed to other methods on this class (e.g. stack() or mosaic()) will be interpreted. It would not usually be used in a normal workflow.

A image collection may contain images from more than one product, introducing the possibility that the band properties for a band of a given name may differ from product to product. This method works in a similar fashion to the Image.scaling_parameters method, but it additionally ensures that the resulting scale elements are compatible across the multiple products. If there is an incompatibility, an appropriate ValueError will be raised.

Parameters:

bands (list(str)) – List of bands to be scaled.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None or str or list or dict) – Band scaling specification. See Image.scaling_parameters for a full description of this parameter.
data_type (None or str) – Result data type desired, as a standard data type string (e.g. "Byte", "Uint16", or "Float64"). If not specified, will be deduced from the scaling specification. See Image.scaling_parameters for a full description of this parameter.

Returns:

scales (list(tuple)) – The fully specified scaling parameter, compatible with the Raster API and the output data type.
data_type (str) – The result data type as a standard GDAL type string.

Raises:

ValueError – If any invalid or incompatible value is passed to any of the three parameters.

See also

Catalog Guide : This contains many examples of the use of the scaling and data_type parameters.

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 descarteslabs.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'))])

stack(bands, geocontext=None, crs=None, resolution=None, all_touched=None, flatten=None, mask_nodata=True, mask_alpha=None, bands_axis=1, raster_info=False, resampler=ResampleAlgorithm.NEAR, processing_level=None, scaling=None, data_type=None, progress=None, max_workers=None)[source]

Load bands from all images and stack them into a 4D ndarray, optionally masking invalid data.

If the selected bands and images have different data types the resulting ndarray has the most general of those data types. See Image.ndarray() for details on data type conversions.

Parameters:

bands (str or Sequence[str]) – Band names to load. Can be a single string of band names separated by spaces ("red green blue"), or a sequence of band names (["red", "green", "blue"]). If the alpha band is requested, it must be last in the list to reduce rasterization errors.
geocontext (GeoContext, default None) – A GeoContext to use when loading each image. If None then the default context of the collection will be used. If this is None, a ValueError is raised.
crs (str, default None) – if not None, update the gecontext with this value to set the output CRS.
resolution (float, default None) – if not None, update the geocontext with this value to set the output resolution in the units native to the specified or defaulted output CRS.
all_touched (float, default None) – if not None, update the geocontext with this value to control rastering behavior.
flatten (str, Sequence[str], callable, or Sequence[callable], default None) –
“Flatten” groups of images in the stack into a single layer by mosaicking each group (such as images from the same day), then stacking the mosaics.

flatten takes the same predicates as Collection.groupby, such as "properties.date" to mosaic images acquired at the exact same timestamp, or ["properties.date.year", "properties.date.month", "properties.date.day"] to combine images captured on the same day (but not necessarily the same time).

This is especially useful when geocontext straddles an image boundary and contains one image captured right after another. Instead of having each as a separate layer in the stack, you might want them combined.

Note that indicies in the returned ndarray will no longer correspond to indicies in this ImageCollection, since multiple images may be combined into one layer in the stack. You can call groupby on this ImageCollection with the same parameters to iterate through groups of images in equivalent order to the returned ndarray.

Additionally, the order of images in the ndarray will change: they’ll be sorted by the parameters to flatten.
mask_nodata (bool, default True) – Whether to mask out values in each band of each image that equal that band’s nodata sentinel value.
mask_alpha (bool or str or None, default None) – Whether to mask pixels in all bands where the alpha band of all images is 0. Provide a string to use an alternate band name for masking. If the alpha band is available for all images in the collection and mask_alpha is None, mask_alpha is set to True. If not, mask_alpha is set to False.
bands_axis (int, default 1) – Axis along which bands should be located. If 1, the array will have shape (image, band, y, x), if -1, it will have shape (image, y, x, band), etc. A bands_axis of 0 is currently unsupported.
raster_info (bool, default False) – Whether to also return a list of dicts about the rasterization of each image, including the coordinate system WKT and geotransform matrix. Generally only useful if you plan to upload data derived from this image back to the Descartes Labs catalog, or use it with GDAL.
resampler (ResampleAlgorithm, default ResampleAlgorithm.NEAR) – Algorithm used to interpolate pixel values when scaling and transforming each image to its new resolution or SRS.
processing_level (str, optional) – How the processing level of the underlying data should be adjusted. Possible values depend on the product and bands in use. Legacy products support toa (top of atmosphere) and in some cases surface. Consult the available processing_levels in the product bands to understand what is available.
scaling (None, str, list, dict) – Band scaling specification. Please see scaling_parameters() for a full description of this parameter.
data_type (None, str) – Output data type. Please see scaling_parameters() for a full description of this parameter.
progress (None, bool) – Controls display of a progress bar.
max_workers (int, default None) – Maximum number of threads to use to parallelize individual ndarray calls to each image. If None, it defaults to the number of processors on the machine, multiplied by 5. Note that unnecessary threads won’t be created if max_workers is greater than the number of images in the ImageCollection.

Returns:

arr (ndarray) – Returned array’s shape is (image, band, y, x) if bands_axis is 1, or (image, y, x, band) if bands_axis is -1. If mask_nodata or mask_alpha is True, arr will be a masked array. The data type (“dtype”) of the array is the most general of the data types among the images being rastered.
raster_info (List[dict]) – If raster_info=True, a list of raster information dicts for each image is also returned

Raises:

ValueError – If requested bands are unavailable, or band names are not given or are invalid. If the context is None and no default context for the ImageCollection is defined, or if not all required parameters are specified in the GeoContext. If the ImageCollection is empty.
NotFoundError – If a Image’s ID cannot be found in the Descartes Labs catalog
BadRequestError – If the Descartes Labs Platform is given unrecognized parameters

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]

property geocontext

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

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

Methods:

`cancel`()	Cancel the upload if it is not yet completed.
`delete`(id[, client, ignore_missing])	You cannot delete an ImageUpload.
`exists`(id[, client])	Checks if an object exists in the Descartes Labs catalog.
`get`(id[, client, request_params])	Get an existing object from the Descartes Labs catalog.
`get_many`(ids[, ignore_missing, client, ...])	Get existing objects from the Descartes Labs catalog.
`get_or_create`(id[, client])	Get an existing object from the Descartes Labs catalog or create a new object.
`reload`()	Reload all attributes from the Descartes Labs catalog.
`save`([request_params])	Saves this object to the Descartes Labs catalog.
`search`([client, includes])	A search query for all uploads.
`serialize`([modified_only, jsonapi_format])	Serialize the catalog object into json.
`update`([ignore_errors])	Update multiple attributes at once using the given keyword arguments.
`wait_for_completion`([timeout, ...])	Wait for the upload to complete.

Attributes:

`ATTRIBUTES`
`created`	The point in time this object was created.
`events`	List of events pertaining to the upload process.
`id`	Globally unique identifier for the upload.
`image`	Image instance with all desired metadata fields.
`image_id`	Image id of the image for this imagery.
`image_upload_options`	Control of the upload process.
`is_modified`	Whether any attributes were changed (see `state`).
`modified`	The point in time this object was last modified.
`product_id`	Product id of the product for this imagery.
`state`	The state of this catalog object.
`status`	Current job status.
`user`	The User ID of the user requesting the upload.

cancel()[source]

Cancel the upload if it is not yet completed.

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

Raises:

NotFoundError – If the object no longer exists.
ValueError – If the catalog object is not in the SAVED state.
DeletedObjectError – If this catalog object was deleted.
ConflictError – If the upload has a current status which does not allow it to be canceled.

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

You cannot delete an ImageUpload.

Raises:: NotImplementedError – This method is not supported for ImageUploads.

classmethod exists(id, client=None)

Checks if an object exists in the Descartes Labs catalog.

Parameters:

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

Returns:

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

Return type:

bool

Raises:

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

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

Get an existing object from the Descartes Labs catalog.

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

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

Parameters:

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

Returns:

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

Return type:

CatalogObject or None

Raises:

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

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

Get existing objects from the Descartes Labs catalog.

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

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

Parameters:

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

Returns:

List of the objects you requested in the same order.

Return type:

list(CatalogObject)

Raises:

NotFoundError – If any of the requested objects do not exist in the Descartes Labs 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, **kwargs)

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

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

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

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

Parameters:

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

Returns:

The requested catalog object that was retrieved or created.

Return type:

CatalogObject

reload()[source]

Reload all attributes from the Descartes Labs catalog.

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

Raises:

NotFoundError – If the object no longer exists.
ValueError – If the catalog object is not in the SAVED state.
DeletedObjectError – If this catalog object was deleted.

save(request_params=None)

Saves this object to the Descartes Labs catalog.

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

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

If this instance was retrieved using get(), get_or_create() or any other way (for example as part of a search()), and none of its values were changed, it will be in the SAVED state, and if no 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 Descartes Labs catalog even though no attributes were modified.

Raises:

ConflictError – If you’re trying to create a new object and the object with given id already exists in the Descartes Labs catalog.
BadRequestError – If any of the attribute values are invalid.
DeletedObjectError – If this catalog object was deleted.
ClientError or ServerError – Spurious exception that can occur during a network request.

Example

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

classmethod search(client=None, includes=True)[source]

A search query for all uploads.

Return an Search instance for searching image uploads.

Parameters:

includes (bool) – Controls the inclusion of events. If True, includes these objects. If False, no events are included. Defaults to True.
client (CatalogClient, optional) – A CatalogClient instance to use for requests to the Descartes Labs catalog.

Returns:

An instance of the Search class

Return type:

Search

Example

>>> from descarteslabs.catalog import (
...     ImageUpload,
...     ImageUploadStatus,
...     properties as p,
... )
>>> search = ImageUpload.search().filter(p.status == ImageUploadStatus.FAILURE)
>>> for result in search: 
...     print(result) 

serialize(modified_only=False, jsonapi_format=False)

Serialize the catalog object into json.

Parameters:

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

update(ignore_errors=False, **kwargs)

Update multiple attributes at once using the given keyword arguments.

Parameters:

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

Raises:

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

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

Wait for the upload to complete.

Parameters:

timeout (int, optional) – If specified, will wait up to specified number of seconds and will raise a concurrent.futures.TimeoutError if the upload has not completed.
warn_transient_errors (bool, optional, default True) – Any transient errors while periodically checking upload status are suppressed. If True, those errors will be printed as warnings.

Raises:

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

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

created

The point in time this object was created.

Filterable, sortable.

Type:: datetime, readonly

events

List of events pertaining to the upload process.

Type:: list(ImageUploadEvent)

id

Globally unique identifier for the upload.

Type:: str

image

Image instance with all desired metadata fields.

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

Type:: Image

image_id

Image id of the image for this imagery.

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

Filterable.

Type:: str

image_upload_options

Control of the upload process.

Type:: ImageUploadOptions

property is_modified

Whether any attributes were changed (see state).

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

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

Type:: bool

modified

The point in time this object was last modified.

Filterable, sortable.

Type:: datetime, readonly

product_id

Product id of the product for this imagery.

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

Filterable, sortable.

Type:: str

property state

The state of this catalog object.

Type:: DocumentState

status

Current job status.

To retrieve the latest status, use reload().

Filterable, sortable.

Type:: str or ImageUploadStatus

user

The User ID of the user requesting the upload.

Filterable, sortable.

Type:: str