Image

Classes

descarteslabs.catalog.Image

ImageUpload

Data Types

descarteslabs.catalog.File

SummaryResult

StorageState

ImageUploadOptions

ImageUploadType

OverviewResampler

ImageUploadStatus


class Image(**kwargs)[source]

An image with raster data.

Parameters

kwargs (dict) – With the exception of readonly attributes (created, modified), any (inherited) attribute listed below can also be used as a keyword argument.

Methods

image_uploads()

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

search([client])

A search query for all images.

upload(files[, upload_options])

Uploads imagery from a file (or files).

upload_ndarray(ndarray[, upload_options, …])

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

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base classes:


geometry

Required: Geometry representing the image coverage. Filterable (use ImageSearch.intersects())

Type

shapely.geometry.base.BaseGeometry, geojson-like

cs_code

The coordinate reference system used by the image as an EPSG or ESRI code, e.g. "EPSG:4326". One of cs_code and projection is required. If both are set and disagree, cs_code takes precedence.

Type

str

projection

The spatial reference system used by the image either as a proj.4 string or a WKT string. One of cs_dode and projection is required. If both are set and disagree, cs_code takes precedence.

Type

str

geotrans

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

Type

list of six float elements

x_pixels

X dimension of the image in pixels

Type

int

y_pixels

Y dimension of the image in pixels

Type

int

acquired

Required: Timestamp when the image was captured by its sensor or created. Filterable, sortable.

Type

str, datetime-like

acquired_end

Timestamp when the image capture by its sensor was completed. Filterable, sortable.

Type

str, datetime-like

published

Timestamp when the data provider published this image. Filterable, sortable.

Type

str, datetime-like

storage_state

Required: Storage state of the image; “available” if the data is available and can be rastered, “remote” if the data is not currently available. Filterable, sortable.

Type

StorageState

files

The list of files holding data for this image.

Type

list(File)

area

Surface are the image covers. Filterable, sortable.

Type

float

azimuth_angle

Sensor azimuth angle in degrees. Filterable, sortable.

Type

float

bits_per_pixel

Average bits of data per pixel per band

Type

list(float)

bright_fraction

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

Type

float

cloud_fraction

Fraction of pixels which are obscured by clouds. Filterable, sortable.

Type

float

alt_cloud_fraction

Fraction of pixels which are obscured by clouds, as per an alternative algorithm. Filterable, sortable.

Type

float

processing_pipeline_id

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

Type

str

fill_fraction

Fraction of this image which has data. Filterable, sortable.

Type

float

incidence_angle

Sensor incidence angle in degrees. Filterable, sortable.

Type

float

reflectance_scale

Scale factors converting TOA radiances to TOA reflectances

Type

list(float)

roll_angle

Applicable only to Landsat 8, roll angle in degrees. Filterable, sortable.

Type

float

solar_azimuth_angle

Solar azimuth angle at capture time. Filterable, sortable.

Type

float

solar_elevation_angle

Solar elevation angle at capture time. Filterable, sortable.

Type

float

view_angle

Sensor view angle in degrees. Filterable, sortable.

Type

float

satellite_id

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

Type

str

provider_id

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

Type

str

provider_url

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

Type

str

preview_url

An external (http) URL to an image that could be inlined in a UI to show a preview for the image

Type

str

preview_file

A GCS URL (gs://) with a georeferenced image that 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

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 search(client=None)[source]

A search query for all images.

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

Parameters

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

Returns

An instance of the ImageSearch class

Return type

ImageSearch

Example

>>> search = Image.search().limit(10)
>>> for result in search:
        print(result.name)
upload(files, upload_options=None)[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.

Parameters
  • files (str or io.IOBase or list 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) – Optional control of the upload process.

Raises

ValueError – If any improper arguments are supplied

Returns

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

Return type

ImageUpload

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

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

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

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

  • upload_options (ImageUploadOptions, optional) – 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 image.geotrans and one of the spatial reference attributes (image.cs_code and image.projection) is unnecessary in this case, but if either of those fields is set in the image parameter then it will take precedence over the value in raster_meta.

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

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

Raises

ValueError – If any improper arguments are supplied

Returns

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

Return type

ImageUpload

class SummaryResult(count=None, bytes=None, products=None, interval_start=None, **kwargs)[source]

The readonly data returned by ImageSearch.summary() or ImageSearch.summary_interval().

count

Number of images in the summary.

Type

int

bytes

Total number of bytes of data across all images in the summary.

Type

int

products

List of IDs for the products included in the summary.

Type

list(str)

interval_start

For interval summaries only, a datetime representing the start of the interval period.

Type

datetime

class ImageUpload(**kwargs)[source]

Request to upload an image.


Attributes

image_id

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

Methods

reload()

Reload all attributes from the Descartes Labs catalog.

wait_for_completion([timeout])

Wait for the upload to complete.

Inheritance

For inherited parameters, methods, attributes, and properties, please refer to the base class:


id

Required: Globally unique identifier for the upload. Generated automatically.

Type

str

product_id

Required: Product id for the Product to which this imagery will be uploaded.

Type

str

image

Required: Image instance with all desired metadata fields (any values will override those determined from the image files themselves). The id field is required.

Type

Image

image_upload_options

Required: At minimum the image_files and upload_type fields must be set.

Type

ImageUploadOptions

resumable_urls

Upload URLs (one per ImageUploadOptions.image_files element) to which the client should upload the file contents.

Type

list(str)

status

Current job status, see ImageUploadStatus.

Type

str

start_datetime

Starting time for upload process.

Type

str, datetime-like

end_datetime

Ending time for upload process.

Type

str, datetime-like

job_id

Unique identifier for the asynchronous upload process.

Type

str

events

List of events pertaining to the upload process.

Type

list

errors

List of any errors encountered during the upload process if the upload failed.

Type

list

reload()[source]

Reload all attributes from the Descartes Labs catalog.

Refresh the state of this catalog object from the object in the Descartes Labs catalog. This way you can refresh the status and other attributes.

Raises
  • NotFoundError – If the object no longer exists

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

wait_for_completion(timeout=None)[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.

:raises TimeoutError: If the specified timeout elapses and the upload has not completed

image_id

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

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

  • _serializable (bool) – Whether this attribute will be included during serialization. Set to True by default. If set to False, the attribute will be skipped during serialized and will throw an AttributeValidationError if serialized explicitly using serialize_attribute.

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

class File(**kwargs)[source]

File definition for an Image.

href

A valid reference to a file object using one of the schemas gs, http, https, ftp, or ftps. Required when the StorageState is AVAILABLE. Optional otherwise.

Type

str

size_bytes

Size of the file in bytes. Required when the StorageState is AVAILABLE.

Type

int

hash

The md5 hash for the given file. Required when the StorageState is AVAILABLE.

Type

str

provider_id

Optional ID for the external provider when the StorageState is REMOTE.

Type

str

provider_href

A URI to describe the remote image in more detail. Either the provider_href or the href must be specified when the StorageState is REMOTE.

Type

str

class StorageState[source]

The storage state for an image.

AVAILABLE

The image data has been uploaded and can be rastered.

Type

enum

REMOTE

The image data is has not been uploaded, but its location is known.

Type

enum

class ImageUploadOptions(**kwargs)[source]

Image upload processing options.

upload_type

Required: Type of upload job, see ImageUploadType.

Type

str

image_files

Required: file basenames of the uploaded files.

Type

list(str)

overviews

Overview generation control, only used when upload_type == ImageUploadType::NDARRAY.

Type

list(int)

overview_resampler

Overview resampler method, only used when upload_type == ImageUploadType::NDARRAY.

Type

OverviewResampler

class ImageUploadType[source]

The type of upload data.

NDARRAY

An multidimensional, homogeneous array of fixed-size items representing one or more images.

Type

enum

FILE

A file on disk containing one or more images.

Type

enum

class OverviewResampler[source]

Allowed overview resampler algorithms.

NEAREST

Applies a nearest neighbour (simple sampling) resampler

Type

enum

AVERAGE

Computes the average of all non-NODATA contributing pixels.

Type

enum

GAUSS

Applies a Gaussian kernel before computing the overview, which can lead to better results than simple averaging in e.g case of sharp edges with high contrast or noisy patterns.

Type

enum

CUBIC

Applies a cubic convolution kernel.

Type

enum

CUBICSPLINE

Applies a B-Spline convolution kernel.

Type

enum

LANCZOS

Applies a Lanczos windowed sinc convolution kernel.

Type

enum

AVERAGE_MP

Averages complex data in mag/phase space.

Type

enum

AVERAGE_MAGPHASE

average_magphase

Type

enum

MODE

Selects the value which appears most often of all the sampled points.

Type

enum

class ImageUploadStatus[source]

The status of the image upload.

UPLOADING

File(s) are being uploaded from client.

PENDING

The files were uploaded, awaiting processing.

RUNNING

The data is being processed.

SUCCESS

The upload completed successfully.

FAILURE

The upload failed; error information is available.

CANCELED

The upload was canceled by the user.