Geospatial

Functions

concat(*imgs)

ImageCollection of imgs concatenated to one another, where

conv2d(obj, filt)

2-D spatial convolution of an Image or ImageCollection.

load_geojson(geojson)

Create a Workflows Geometry, GeometryCollection, Feature, or FeatureCollection from a GeoJSON mapping.

load_geojson_file(path)

Create a Workflows Geometry, GeometryCollection, Feature, or FeatureCollection from a GeoJSON file.

where(condition, x, y)

Returns an Image or ImageCollection with values chosen from x or y depending on condition.

Classes

Kernel(dims, data)

A Kernel is a proxy object holding the kernel when performing a 2-dimensional convolution.

Feature(geometry, properties)

Proxy GeoJSON Feature representing a Geometry and a Dict of properties.

FeatureCollection(features)

Proxy GeoJSON FeatureCollection constructed from a sequence of Features.

GeoContext([geometry, resolution, crs, …])

Proxy scenes.geocontext.GeoContext containing the spatial parameters (AOI, resolution, etc.) to use when loading geospatial data.

Geometry(type, coordinates)

Proxy GeoJSON Geometry representing a geometry’s type and coordinates.

GeometryCollection(geometries[, type])

Proxy GeoJSON GeometryCollection constructed from a sequence of Geometries.

ImageCollectionGroupby(imgs, func)

Dict-like object for a grouped ImageCollection.

Image()

Proxy Image; construct with from_id or from_scenes.

ImageCollection(images)

Proxy object representing a stack of Images; typically construct with from_id.

class Kernel(dims, data)[source]

A Kernel is a proxy object holding the kernel when performing a 2-dimensional convolution.

Examples

Methods

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

Attributes

data

List containing the kernel data in row-major format

dims

Tuple containing the dimensions of the kernel

>>> from descarteslabs.workflows import Kernel
>>> kernel = Kernel(dims=(5,5), data=[1.0, 1.0, 1.0, 1.0, 1.0,
...                                   1.0, 2.0, 3.0, 2.0, 1.0,
...                                   1.0, 3.0, 4.0, 3.0, 1.0,
...                                   1.0, 2.0, 3.0, 2.0, 1.0,
...                                   1.0, 1.0, 1.0, 1.0, 1.0])
>>> kernel
<descarteslabs.workflows.types.geospatial.convolution.Kernel object at 0x...>
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

property data

List containing the kernel data in row-major format

Type

List[Float]

property dims

Tuple containing the dimensions of the kernel

Type

Tuple[Int, Int]

class Feature(geometry, properties)[source]

Proxy GeoJSON Feature representing a Geometry and a Dict of properties.

Examples

Methods

buffer(distance)

Buffer the area around self by a given distance.

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

from_geojson(geojson)

Construct a Workflows Feature from a GeoJSON mapping.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

rasterize([value, default_value])

Rasterize this Feature into an Image

Attributes

geometry

Geometry

properties

Dict[Str, Any]

>>> from descarteslabs.workflows import Geometry, Feature
>>> geom = Geometry(type="Point", coordinates=[1, 2])
>>> feat = Feature(geometry=geom, properties={"foo": "bar"})
>>> feat
<descarteslabs.workflows.types.geospatial.feature.Feature object at 0x...>
>>> feat.compute() 
FeatureResult(geometry=GeometryResult(type=Point, coordinates=[1, 2]), properties={'foo': 'bar'})
>>> # constructing same Feature as previous example, but using from_geojson
>>> from descarteslabs.workflows import Feature
>>> geojson = {"type": "Feature",
...            "geometry": {"type": "Point", "coordinates": [1, 2]},
...            "properties": {"foo": "bar"}}
>>> feat = Feature.from_geojson(geojson)
>>> feat.compute().__geo_interface__ 
{'type': 'Feature',
 'geometry': {'type': 'Point', 'coordinates': [1, 2]},
 'properties': {'foo': 'bar'}}
buffer(distance)

Buffer the area around self by a given distance.

Parameters

distance (Int or Float) – The distance (in decimal degrees) to buffer the area around the Geometry.

Returns

Return type

Same type as self

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> buffered = geom.buffer(2)
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

classmethod from_geojson(geojson)[source]

Construct a Workflows Feature from a GeoJSON mapping.

Note that the GeoJSON must be relatively small (under 10MiB of serialized JSON).

Parameters

geojson (Dict) –

Returns

Return type

Feature

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

rasterize(value=1, default_value=1)[source]

Rasterize this Feature into an Image

Parameters
  • value (Int, Float, Str, default=1) – Fill pixels within the Feature with this value. Pixels outside the Feature will be masked, and set to 0. If a string, it will look up that key in self.properties; the value there must be a number.

  • default_value (Int, Float, default=1) – Value to use if value is a string and the key does not exist in self.properties

Notes

Rasterization happens according to the GeoContext of the Job, so the geometry is projected into and rasterized at that CRS and resolution.

Returns

rasterized – An Image with 1 band named "features", the same properties as this Feature, and empty bandinfo.

Return type

Image

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> feat = wf.Feature(geometry=geom, properties={"foo": 2})
>>> feat.rasterize(value=0.5)
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
>>> feat.rasterize(value=0.5).mean().compute(geoctx) 
0.5
>>> feat.rasterize(value="foo").mean().compute(geoctx) 
2
property geometry

Geometry

property properties

Dict[Str, Any]

class FeatureCollection(features)[source]

Proxy GeoJSON FeatureCollection constructed from a sequence of Features.

Examples

Methods

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

contains(other)

Contains is equivalient to the Python in operator.

filter(func)

Filter elements from an iterable proxytype.

from_geojson(geojson)

Construct a Workflows FeatureCollection from a GeoJSON mapping.

from_vector_id(id)

Construct a Workflows FeatureCollection from a vector ID.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

length()

Length is equivalent to the Python len operator.

map(func)

Map a function over an iterable proxytype.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

rasterize([value, default_value, …])

Rasterize all Features into one Image

reduce(func[, initial])

Reduce a collection of elements to a single element.

sorted(key[, reverse])

Copy of this FeatureCollection, sorted by a key function.

Attributes

features

List[Feature]

>>> from descarteslabs.workflows import Geometry, Feature, FeatureCollection
>>> geom = Geometry(type="Point", coordinates=[1, 2])
>>> feat = Feature(geometry=geom, properties={"foo": "bar"})
>>> fc = FeatureCollection(features=[feat, feat, feat])
>>> fc
<descarteslabs.workflows.types.geospatial.featurecollection.FeatureCollection object at 0x...>
>>> fc.compute() 
FeatureCollectionResult(features=(
    FeatureResult(geometry=GeometryResult(type=Point, coordinates=[1, 2]), properties={'foo': 'bar'}),
    FeatureResult(geometry=GeometryResult(type=Point, coordinates=[1, 2]), properties={'foo': 'bar'}),
    FeatureResult(geometry=GeometryResult(type=Point, coordinates=[1, 2]), properties={'foo': 'bar'})))
>>> # constructing similar FeatureCollection to previous example, but using from_geojson
>>> from descarteslabs.workflows import FeatureCollection
>>> geojson = {
...     "type": "FeatureCollection",
...     "features": [
...         {
...             "type": "Feature",
...             "geometry": {"type": "Point", "coordinates": [1, 2]},
...             "properties": {"foo": "bar"},
...         }
...     ],
... }
>>> fc = FeatureCollection.from_geojson(geojson)
>>> fc.compute().__geo_interface__ 
{'type': 'FeatureCollection',
 'features': [{'type': 'Feature',
   'geometry': {'type': 'Point', 'coordinates': [1, 2]},
   'properties': {'foo': 'bar'}}]}

Construct a FeatureCollection from a sequence of Features.

compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

contains(other)

Contains is equivalient to the Python in operator.

Parameters

other (Proxytype) – A Proxytype or type that can be promoted to a Proxytype

Returns

A Bool Proxytype

Return type

Bool

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 2, 3])
>>> my_list.contains(2).compute() 
True
filter(func)

Filter elements from an iterable proxytype.

Parameters

func (Python callable) – A function that takes a single argument and returns a Bool Proxytype.

Returns

A Proxytype of the same type having only the elements where func returns True.

Return type

Proxtype

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("sentinel-2:L1C")
>>> filtered = col.filter(lambda img: img.properties["date"].year == 2018)
classmethod from_geojson(geojson)[source]

Construct a Workflows FeatureCollection from a GeoJSON mapping.

Note that the GeoJSON must be relatively small (under 10MiB of serialized JSON).

Parameters

geojson (Dict) –

Returns

Return type

FeatureCollection

classmethod from_vector_id(id)[source]

Construct a Workflows FeatureCollection from a vector ID.

The FeatureCollection will contain every Feature within the GeoContext used in the computation.

Parameters

id (Str) – An ID of a product in the Descartes Labs Vector service.

Returns

Return type

FeatureCollection

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

length()

Length is equivalent to the Python len operator.

Returns

An Int Proxytype

Return type

Int

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 2, 3])
>>> my_list.length().compute() 
3
map(func)

Map a function over an iterable proxytype.

Parameters

func (Python callable) – A function that takes a single argument and returns another proxytype.

Returns

The return type is dependent on the func and the type of the element returned. For example, calling map over an ImageCollection with a function that returns the date of the Image will now be a List[Datetime].

Return type

Proxtype

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

rasterize(value=1, default_value=1, merge_algorithm='add')[source]

Rasterize all Features into one Image

Parameters
  • value (Int, Float, Str, default=1) –

    Fill enclosed pixels with this value. Pixels outside the FeatureCollection will be masked, and set to 0.

    If a string, it will look up that key in the properties of each Feature; the value there must be a number.

  • default_value (Int, Float, default=1) – Value to use if value is a string and the key does not exist in the properties of a Feature.

  • merge_algorithm (Str, default="add") – How to combine values where Features overlap. Options are "add", to sum the values, or "replace", to use the value from the Feature that comes last in the FeatureCollection.

Notes

Rasterization happens according to the GeoContext of the Job, so the geometry is projected into and rasterized at that CRS and resolution.

Returns

rasterized – An Image with 1 band named "features", and empty properties and bandinfo.

Return type

Image

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> feat = wf.Feature(geometry=geom, properties={"foo": 1})
>>> fc = wf.FeatureCollection(features=[feat, feat, feat])
>>> fc.rasterize(value=0.5)
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
>>> fc.rasterize(value="foo").max().compute(geoctx) 
3
>>> fc.rasterize(value="foo", merge_algorithm="replace").max().compute(geoctx) 
1
reduce(func, initial='__NO_INITIAL_REDUCE_VALUE__')

Reduce a collection of elements to a single element.

NOTE: Optimized reducers such as sum have been implemented for some classes.

Parameters
  • func (Python callable) – A function where the left argument is the accumulated value (the result of the previous call to func) and the right argument is the next value from the iterable. The function should return a single proxtype.

  • initial (Proxytype, optional) – An optional proxtype to provide for the first iteration. If no value is provided, the first element will be used.

Returns

The return value of func for the last iteration of the collection.

Return type

Proxytype

Example

>>> from descarteslabs.workflows import List, Int
>>> def add(accumulated, current):
...     return accumulated + current
>>> my_list = List[Int]([1, 2])
>>> my_list.reduce(add, initial=Int(10)).compute()  
13
sorted(key, reverse=False)[source]

Copy of this FeatureCollection, sorted by a key function.

Parameters
  • key (Function) – Function which takes an Feature and returns a value to sort by.

  • reverse (Bool, default False) – Sorts in ascending order if False (default), descending if True.

Returns

sorted

Return type

FeatureCollection

property features

List[Feature]

class GeoContext(geometry=None, resolution=None, crs=None, align_pixels=True, bounds=None, bounds_crs='EPSG:4326', shape=None)[source]

Proxy scenes.geocontext.GeoContext containing the spatial parameters (AOI, resolution, etc.) to use when loading geospatial data. Equivalent to a scenes.geocontext.AOI, with the additional read-only properties arr_shape, gdal_geotrans, and projected_bounds.

You don’t often need to construct a Workflows GeoContext yourself. When you call compute(), you can pass in any scenes.geocontext.GeoContext, or use wf.map.geocontext() for the current map viewport.

Note: The raster_params of a GeoContext can be passed to raster.ndarray to get an equivalent array.

Examples

Attributes

align_pixels

Snap the bounds to whole-number intervals of resolution, ensuring non-fractional pixels.

arr_shape

(height, width) (i.e. (rows, cols)) of the array this GeoContext will produce.

bounds

Clip data to these (min_x, min_y, max_x, max_y) bounds, expressed in the coordinate reference system in bounds_crs.

bounds_crs

The coordinate reference system of the bounds, expressed as an EPSG code (like EPSG:4326) or a PROJ.4 definition.

crs

Coordinate reference system into which data will be projected, expressed as an EPSG code (like EPSG:4326) or a PROJ.4 definition.

gdal_geotrans

The 6-element GDAL geotrans this GeoContext will use.

geometry

Clip data to this Geometry (like a cutline).

projected_bounds

The actual bounds (in units of crs), if the bounds_crs convenience is used.

resolution

Distance, in units of the crs, that the edge of each pixel represents on the ground.

shape

The dimensions (rows, columns), in pixels, to fit the output array within.

Methods

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

coords_to_index(x, y)

Convert spatial coordinates (x, y) in the GeoContext’s CRS to pixel coordinates (row, col).

from_dltile_key(key)

Construct a Workflows GeoContext from a DLTile key.

from_scenes(ctx)

Construct a Workflows GeoContext from a Scenes GeoContext

from_xyz_tile(x, y, z)

Construct a Workflows GeoContext for an XYZ tile in the OpenStreetMap tiling scheme.

index_to_coords(row, col)

Convert pixel coordinates (row, col) to spatial coordinates (x, y) in the GeoContext’s CRS.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

>>> from descarteslabs.workflows import GeoContext
>>> from descarteslabs import scenes
>>> scene = scenes.DLTile.from_latlon(10, 30, resolution=10, tilesize=512, pad=0)
>>> # the above scene could be passed to compute without being changed to a Workflows GeoContext
>>> geoctx = GeoContext.from_scenes(scene)
>>> geoctx
<descarteslabs.workflows.types.geospatial.geocontext.GeoContext object at 0x...>
>>> geoctx.compute() 
{'geometry': {'type': 'Polygon',
  'coordinates': (((29.964809031113013, 9.990748782946097),
    (30.011460043000678, 9.991170922969406),
    (30.011036444452188, 10.03741571582387),
    (29.964378844777645, 10.036991583007385),
    (29.964809031113013, 9.990748782946097)),)},
 'key': '512:0:10.0:36:-65:216',
 'resolution': 10.0,
 'tilesize': 512,
 'pad': 0,
 'crs': 'EPSG:32636',
 'bounds': (167200.0, 1105920.0, 172320.0, 1111040.0),
 'bounds_crs': 'EPSG:32636',
 'zone': 36,
 'ti': -65,
 'tj': 216,
 'proj4': '+proj=utm +zone=36 +datum=WGS84 +units=m +no_defs ',
 'wkt': 'PROJCS["WGS 84 / UTM zone 36N",GEOGCS["WGS 84",
         DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,
         AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],
         PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],
         UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],
         AUTHORITY["EPSG","4326"]],PROJECTION["Transverse_Mercator"],
         PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",33],
         PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],
         PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],
         AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","32636"]]',
 'projected_bounds': (167200.0, 1105920.0, 172320.0, 1111040.0),
 'arr_shape': (512, 512),
 'align_pixels': False,
 'geotrans': (10.0, 0.0, 167200.0, 0.0, -10.0, 1111040.0, 0.0, 0.0, 1.0),
 'gdal_geotrans': (167200.0, 10.0, 0.0, 1111040.0, 0.0, -10.0),
 'raster_params': {'dltile': '512:0:10.0:36:-65:216', 'align_pixels': False}}
>>> from descarteslabs.workflows import GeoContext
>>> geoctx = GeoContext.from_dltile_key('512:0:10.0:36:-65:216')
>>> geoctx
<descarteslabs.workflows.types.geospatial.geocontext.GeoContext object at 0x...>
>>> geoctx.compute() 
{'geometry': {'type': 'Polygon',
              'coordinates': (((29.964809031113013, 9.990748782946097),
                               (30.011460043000678, 9.991170922969406),
                               (30.011036444452188, 10.03741571582387),
                               (29.964378844777645, 10.036991583007385),
                               (29.964809031113013, 9.990748782946097)),)},
 'key': '512:0:10.0:36:-65:216',
 'resolution': 10.0,
 'tilesize': 512,
...
>>> from descarteslabs.workflows import GeoContext
>>> geoctx = GeoContext.from_xyz_tile(1, 2, 3)
>>> geoctx
<descarteslabs.workflows.types.geospatial.geocontext.GeoContext object at 0x...>
>>> geoctx.compute() 
{'x': 1,
 'y': 2,
 'z': 3,
 'geometry': {'type': 'Polygon',
 'coordinates': (((-90.0, 40.97989806962013),
                  (-90.0, 66.51326044311186),
                  (-135.0, 66.51326044311186),
                  (-135.0, 40.97989806962013),
                  (-90.0, 40.97989806962013)),)},
 'tilesize': 256,
 'crs': 'EPSG:3857',
...
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

coords_to_index(x, y)[source]

Convert spatial coordinates (x, y) in the GeoContext’s CRS to pixel coordinates (row, col).

classmethod from_dltile_key(key)[source]

Construct a Workflows GeoContext from a DLTile key.

Parameters

key (Str) –

Returns

Return type

GeoContext

classmethod from_scenes(ctx)[source]

Construct a Workflows GeoContext from a Scenes GeoContext

Parameters

ctx (AOI, DLTile, or XYZTile) –

Returns

Return type

GeoContext

classmethod from_xyz_tile(x, y, z)[source]

Construct a Workflows GeoContext for an XYZ tile in the OpenStreetMap tiling scheme.

Parameters
Returns

Return type

GeoContext

index_to_coords(row, col)[source]

Convert pixel coordinates (row, col) to spatial coordinates (x, y) in the GeoContext’s CRS.

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

property align_pixels

Snap the bounds to whole-number intervals of resolution, ensuring non-fractional pixels.

Imagine the bounds overlayed on on a grid of resolution (say, 30m) intervals. align_pixels expands the bounds outward to the next grid lines.

Type

Bool

property arr_shape

(height, width) (i.e. (rows, cols)) of the array this GeoContext will produce.

This derived property (computed from projected_bounds, resolution, and align_pixels) cannot be set in __init__, but you can call compute on it (useful for uploading to Catalog).

Type

Tuple[Int, Int]

property bounds

Clip data to these (min_x, min_y, max_x, max_y) bounds, expressed in the coordinate reference system in bounds_crs.

If bounds_crs and crs differ, the actual bounds will be the envelope of the rectangle defined by bounds, when reprojected into crs.

Type

Tuple[Float, Float, Float, Float]

property bounds_crs

The coordinate reference system of the bounds, expressed as an EPSG code (like EPSG:4326) or a PROJ.4 definition.

Type

Str

property crs

Coordinate reference system into which data will be projected, expressed as an EPSG code (like EPSG:4326) or a PROJ.4 definition.

Type

Str

property gdal_geotrans

The 6-element GDAL geotrans this GeoContext will use.

This tuple is in the form (a, b, c, d, e, f), where:

  • a: top left pixel’s x-coordinate

  • b: west-east pixel resolution

  • c: row rotation; always 0 for GeoContext

  • d: top left pixel’s y-coordinate

  • e: column rotation; always 0 for GeoContext

  • f: north-south pixel resolution, always a negative value

This derived property (computed from projected_bounds, resolution, and align_pixels) cannot be set in __init__, but you can call compute on it (useful for uploading to Catalog).

Type

Tuple[Float, Float, Float, Float, Float, Float]

property geometry

Clip data to this Geometry (like a cutline).

Coordinates must be WGS84 (lat-lon). If None, data will just be clipped to bounds.

Type

Geometry

property projected_bounds

The actual bounds (in units of crs), if the bounds_crs convenience is used.

This is the envelope of the four corners defined by bounds, when those corners are reprojected from bounds_crs into crs.

This derived property cannot be set in __init__, but you can call compute on it (useful for uploading to Catalog).

Type

Tuple[Float, Float, Float, Float]

property resolution

Distance, in units of the crs, that the edge of each pixel represents on the ground.

Type

Float

property shape

The dimensions (rows, columns), in pixels, to fit the output array within.

Type

Tuple[Int, Int]

class Geometry(type, coordinates)[source]

Proxy GeoJSON Geometry representing a geometry’s type and coordinates.

Examples

Methods

buffer(distance)

Buffer the area around self by a given distance.

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

from_geo_interface(obj)

Construct a Workflows Geometry from a __geo_interface__.

from_geojson(geojson)

Construct a Workflows Geometry from a GeoJSON mapping.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

rasterize([value])

Rasterize this Geometry into an Image

Attributes

coordinates

List[Any]

type

Str

>>> from descarteslabs.workflows import Geometry
>>> geom = Geometry(type="Point", coordinates=[1, 2])
>>> geom
<descarteslabs.workflows.types.geospatial.geometry.Geometry object at 0x...>
>>> geom.compute() 
GeometryResult(type=Point, coordinates=[1, 2])
>>> # constructing same Geometry as previous example, but using from_geojson
>>> from descarteslabs.workflows import Geometry
>>> geojson = {"type": "Point", "coordinates": [1, 2]}
>>> geom = Geometry.from_geojson(geojson)
>>> geom.compute().__geo_interface__ 
{'type': 'Point', 'coordinates': [1, 2]}
buffer(distance)

Buffer the area around self by a given distance.

Parameters

distance (Int or Float) – The distance (in decimal degrees) to buffer the area around the Geometry.

Returns

Return type

Same type as self

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> buffered = geom.buffer(2)
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

classmethod from_geo_interface(obj)[source]

Construct a Workflows Geometry from a __geo_interface__.

Parameters

obj (object with a __geo_interface__ attribute) – See https://gist.github.com/sgillies/2217756 for information about the __geo_interface__ attribute

Returns

Return type

Geometry

classmethod from_geojson(geojson)[source]

Construct a Workflows Geometry from a GeoJSON mapping.

Note that the GeoJSON must be relatively small (under 10MiB of serialized JSON).

Parameters

geojson (Dict) –

Returns

Return type

Geometry

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

rasterize(value=1)

Rasterize this Geometry into an Image

Parameters

value (Int, Float, default=1) – Fill pixels within the Geometry with this value. Pixels outside the Geometry will be masked, and set to 0.

Note

Rasterization happens according to the GeoContext of the Job, so the geometry is projected into and rasterized at that CRS and resolution.

Returns

rasterized – An Image with 1 band named "features", and empty properties and bandinfo.

Return type

Image

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> geom.rasterize(value=0.5)
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
property coordinates

List[Any]

property type

Str

class GeometryCollection(geometries, type='GeometryCollection')[source]

Proxy GeoJSON GeometryCollection constructed from a sequence of Geometries.

Examples

Methods

buffer(distance)

Take the envelope of all the geometries, and buffer that by a given distance.

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

contains(other)

Contains is equivalient to the Python in operator.

filter(func)

Filter elements from an iterable proxytype.

from_geojson(geojson)

Construct a Workflows GeometryCollection from a GeoJSON mapping.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

length()

Length is equivalent to the Python len operator.

map(func)

Map a function over an iterable proxytype.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

rasterize([value])

Rasterize this Geometry into an Image

reduce(func[, initial])

Reduce a collection of elements to a single element.

sorted([key, reverse])

Copy of this collection, sorted by a key function.

Attributes

geometries

List[Geometry]

type

Str

>>> from descarteslabs.workflows import Geometry, GeometryCollection
>>> geom = Geometry(type="Point", coordinates=[1, 2])
>>> gc = GeometryCollection(geometries=[geom, geom, geom])
>>> gc
<descarteslabs.workflows.types.geospatial.geometrycollection.GeometryCollection object at 0x...>
>>> gc.compute() 
GeometryCollectionResult(type=GeometryCollection,
        geometries=(
            GeometryResult(type=Point, coordinates=[1, 2]),
            GeometryResult(type=Point, coordinates=[1, 2]),
            GeometryResult(type=Point, coordinates=[1, 2])))
>>> # constructing similar GeometryCollection to previous example, but using from_geojson
>>> from descarteslabs.workflows import GeometryCollection
>>> geojson = {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [1, 2]}]}
>>> gc = GeometryCollection.from_geojson(geojson)
>>> gc.compute().__geo_interface__ 
{'type': 'GeometryCollection', 'geometries': [{'type': 'Point', 'coordinates': [1, 2]}]}
buffer(distance)[source]

Take the envelope of all the geometries, and buffer that by a given distance.

Parameters

distance (Int or Float) – The distance (in decimal degrees) to buffer the area around the Geometry.

Returns

Return type

Geometry

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> gc = wf.GeometryCollection(geometries=[geom, geom, geom])
>>> gc.buffer(2)
<descarteslabs.workflows.types.geospatial.geometry.Geometry object at 0x...>
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

contains(other)

Contains is equivalient to the Python in operator.

Parameters

other (Proxytype) – A Proxytype or type that can be promoted to a Proxytype

Returns

A Bool Proxytype

Return type

Bool

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 2, 3])
>>> my_list.contains(2).compute() 
True
filter(func)

Filter elements from an iterable proxytype.

Parameters

func (Python callable) – A function that takes a single argument and returns a Bool Proxytype.

Returns

A Proxytype of the same type having only the elements where func returns True.

Return type

Proxtype

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("sentinel-2:L1C")
>>> filtered = col.filter(lambda img: img.properties["date"].year == 2018)
classmethod from_geojson(geojson)[source]

Construct a Workflows GeometryCollection from a GeoJSON mapping.

Note that the GeoJSON must be relatively small (under 10MiB of serialized JSON).

Parameters

geojson (Dict) –

Returns

Return type

GeometryCollection

Example

>>> from descarteslabs.workflows import GeometryCollection
>>> geojson = {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [1, 2]}]}
>>> gc = GeometryCollection.from_geojson(geojson)
>>> gc.compute().__geo_interface__ 
{'type': 'GeometryCollection', 'geometries': [{'type': 'Point', 'coordinates': [1, 2]}]}
inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

length()[source]

Length is equivalent to the Python len operator.

Returns

An Int Proxytype

Return type

Int

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 2, 3])
>>> my_list.length().compute() 
3
map(func)

Map a function over an iterable proxytype.

Parameters

func (Python callable) – A function that takes a single argument and returns another proxytype.

Returns

The return type is dependent on the func and the type of the element returned. For example, calling map over an ImageCollection with a function that returns the date of the Image will now be a List[Datetime].

Return type

Proxtype

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

rasterize(value=1)

Rasterize this Geometry into an Image

Parameters

value (Int, Float, default=1) – Fill pixels within the Geometry with this value. Pixels outside the Geometry will be masked, and set to 0.

Note

Rasterization happens according to the GeoContext of the Job, so the geometry is projected into and rasterized at that CRS and resolution.

Returns

rasterized – An Image with 1 band named "features", and empty properties and bandinfo.

Return type

Image

Example

>>> import descarteslabs.workflows as wf
>>> geom = wf.Geometry(type="Point", coordinates=[1, 2])
>>> geom.rasterize(value=0.5)
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
reduce(func, initial='__NO_INITIAL_REDUCE_VALUE__')

Reduce a collection of elements to a single element.

NOTE: Optimized reducers such as sum have been implemented for some classes.

Parameters
  • func (Python callable) – A function where the left argument is the accumulated value (the result of the previous call to func) and the right argument is the next value from the iterable. The function should return a single proxtype.

  • initial (Proxytype, optional) – An optional proxtype to provide for the first iteration. If no value is provided, the first element will be used.

Returns

The return value of func for the last iteration of the collection.

Return type

Proxytype

Example

>>> from descarteslabs.workflows import List, Int
>>> def add(accumulated, current):
...     return accumulated + current
>>> my_list = List[Int]([1, 2])
>>> my_list.reduce(add, initial=Int(10)).compute()  
13
sorted(key=None, reverse=False)

Copy of this collection, sorted by a key function.

Parameters
  • key (Function, optional, default None) – Function which takes an element and returns a value to sort by. If not given, sorts by the elements themselves.

  • reverse (Bool, default False) – Sorts in ascending order if False (default), descending if True.

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 4, 2, 3])
>>> my_list.sorted().compute() 
[1, 2, 3, 4]
property geometries

List[Geometry]

property type

Str

class ImageCollectionGroupby(imgs, func)[source]

Dict-like object for a grouped ImageCollection.

If constructed from an empty ImageCollection or func results in empty groups, ImageCollectionGroupby.groups will return an empty Dict. Other operations (like map and count) will also return an empty Dict or an empty Image/ImageCollection.

Groups can be accessed with dict-like syntax. If indexing with a key that does not exist, an empty ImageCollection is returned.

Examples

Methods

compute(*args, **kwargs)

Compute this proxy object and wait for its result.

count([axis])

Apply ImageCollection.count to each group.

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

map(func)

Apply a function to each group as an ImageCollection and combine the results.

max([axis])

Apply ImageCollection.max to each group.

mean([axis])

Apply ImageCollection.mean to each group.

median([axis])

Apply ImageCollection.median to each group.

min([axis])

Apply ImageCollection.min to each group.

mosaic([reverse])

Apply ImageCollection.mosaic to each group.

one()

A Tuple of (group key, ImageCollection) for one random group.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

std([axis])

Apply ImageCollection.std to each group.

sum([axis])

Apply ImageCollection.sum to each group.

Attributes

groups

Dict of group key -> ImageCollection

key_type

The type of the group keys

>>> import descarteslabs.workflows as wf
>>> from descarteslabs.scenes import DLTile
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> # all Images from the same month, regardless of year
>>> col.groupby(dates="month")
<descarteslabs.workflows.types.geospatial.groupby.ImageCollectionGroupby[Int] object at 0x...>
>>>
>>> # group into 14-day bins
>>> col.groupby(lambda img: img.properties["date"] // wf.Timedelta(days=14))
<descarteslabs.workflows.types.geospatial.groupby.ImageCollectionGroupby[Datetime] object at 0x...>
>>>
>>> # group by "pass" ("ASCENDING" or "DESCENDING")
>>> col.groupby(lambda img: img.properties["pass"])
<descarteslabs.workflows.types.geospatial.groupby.ImageCollectionGroupby[Any] object at 0x...>
>>>
>>> # all Images from the same year and month
>>> month_grouped = col.groupby(dates=("year", "month"))
>>>
>>> # .mean(), etc. are applied to each group, then combined into one ImageCollection
>>> monthly = month_grouped.mean(axis="images")  # ImageCollection of monthly mean composites
>>>
>>> # a `group` field is added to each Image
>>> monthly.map(lambda img: img.properties['group']).compute(geoctx) 
[(2018, 1), (2018, 2), ... ]
>>>
>>> # use .map() to apply a function to each group, then combine into a Dict or ImageCollection
>>> monthly_l2_norm = month_grouped.map(lambda group, imgs: (imgs ** 2).sum(axis="images").sqrt())
>>> # ^ ImageCollection of each month's L2 norm
>>>
>>> monthly_medians = month_grouped.map(lambda group, imgs: imgs.median())
>>> # ^ Dict of (year, month) to median pixel value
>>>
>>> # you can select a single group with dict-like syntax
>>> feb = month_grouped[(2018, 2)]
>>> feb.compute(geoctx) 
ImageCollectionResult of length 2:
...
>>> # selecting a non-existent group returns an empty ImageCollection
>>> month_grouped[(1900, 1)].compute(geoctx) 
ImageCollectionResult of length 0:
...

You should construct ImageCollectionGroupby from ImageCollection.groupby in most cases.

Parameters
Returns

grouped

Return type

ImageCollectionGroupby

compute(*args, **kwargs)[source]

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

count(axis=None)[source]

Apply ImageCollection.count to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.count(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.count(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.count(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.count(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.count(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.count(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

map(func)[source]

Apply a function to each group as an ImageCollection and combine the results.

func must take two arguments: the group, and an ImageCollection of all Images in that group.

If it returns an ImageCollection, the ImageCollections for all groups will be concatenated together.

If it returns an Image, those Images will be combined into a single ImageCollection.

If it returns any other type, map will return a Dict, where keys are groups and values are results of func.

Note that every Image in every ImageCollecion gets a "group" field added to its properties, so that field will be merged/dropped according to normal metadata broadcasting rules (i.e. will still be present on an Image composited from a group’s ImageCollection, since it’s the same for every Image.)

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(dates="month")
>>> groups.map(lambda group, col: col.pick_bands("red green blue"))# pick rgb bands for each group
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> # since the mapper function returns an ImageCollection, they are combined back into a single collection
>>> # each have a group key in their properties
>>> groups.map(lambda group, col: col.mean()) # equivalent to groups.mean()
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at...>
>>> # since the mapper function returns a Dict, map returns a Dict of group key to func results
max(axis=None)[source]

Apply ImageCollection.max to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.max(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.max(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.max(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.max(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.max(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.max(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
mean(axis=None)[source]

Apply ImageCollection.mean to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.mean(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.mean(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.mean(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.mean(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.mean(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.mean(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
median(axis=None)[source]

Apply ImageCollection.median to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.median(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.median(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.median(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.median(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.median(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.median(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
min(axis=None)[source]

Apply ImageCollection.min to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.min(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.min(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.min(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.min(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.min(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.min(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
mosaic(reverse=False)[source]

Apply ImageCollection.mosaic to each group.

Always returns an ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.mosaic()
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
one()[source]

A Tuple of (group key, ImageCollection) for one random group. Helpful for debugging.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(dates="month")
>>> groups.one().compute(geoctx) 
(5, ImageCollection...)
publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

std(axis=None)[source]

Apply ImageCollection.std to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.std(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.std(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.std(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.std(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.std(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.std(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
sum(axis=None)[source]

Apply ImageCollection.sum to each group.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> groups = col.groupby(lambda img: img.properties["date"].month)
>>> groups.sum(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.sum(axis="bands")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> groups.sum(axis="pixels")
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Dict[Str, Float]]] object at 0x...>
>>> groups.sum(axis=("bands", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, List[Float]] object at 0x...>
>>> groups.sum(axis=("images", "pixels"))
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Dict[Str, Float]] object at 0x...>
>>> groups.sum(axis=None)
<descarteslabs.workflows.types.containers.dict_.Dict[Int, Float] object at 0x...>
property groups

Dict of group key -> ImageCollection

property key_type

The type of the group keys

Type

Proxytype

class Image[source]

Proxy Image; construct with from_id or from_scenes.

An Image is a proxy object holding multiple (ordered) bands of raster data, plus some metadata.

Images don’t have a set spatial extent, CRS, resolution, etc: that’s determined at computation time by the GeoContext passsed in.

Supports unary operations such as negation and absolute value, as well as arithmetic and comparison operators such as >, +, and //.

Examples

Methods

arccos()

Element-wise inverse cosine of an Image.

arcsin()

Element-wise inverse sine of an Image.

arctan()

Element-wise inverse tangent of an Image.

clip_values([min, max])

Given an interval, band values outside the interval are clipped to the interval edge.

colormap([named_colormap, vmin, vmax])

Apply a colormap to an Image.

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

concat(*imgs)

ImageCollection with imgs concatenated onto this Image, where

concat_bands(other_image)

New Image, with the bands in other_image appended to this one.

coords_to_index(x, y)

Convert spatial coordinates (x, y) to pixel coordinates (row, col) in the Image.

cos()

Element-wise cosine of an Image.

count([axis])

Count of valid (unmasked) pixels across the provided axis, or across all pixels in the image if no axis argument is provided.

exp()

Element-wise exponential of an Image.

from_id(image_id[, resampler, processing_level])

Create a proxy Image from an ID in the Descartes Labs catalog.

from_scene(scene)

Create a proxy image from a Scene object

getmask()

Mask of this Image, as a new Image with one boolean band named 'mask'.

index_to_coords(row, col)

Convert pixel coordinates (row, col) in the ImageCollection into spatial coordinates (x, y).

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

log()

Element-wise natural log of an Image.

log10()

Element-wise base 10 log of an Image.

log1p()

Element-wise log of 1 + an Image.

log2()

Element-wise base 2 log of an Image.

map_bands(func)

Map a function over each band in self.

mask(mask[, replace])

New Image, masked with a boolean Image or vector object.

max([axis])

Maximum pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

mean([axis])

Mean pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

median([axis])

Median pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

min([axis])

Minimum pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

pick_bands(bands[, allow_missing])

New Image, containing only the given bands.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

rename_bands(*new_positional_names, **new_names)

New Image, with bands renamed by position or name.

replace_empty_with(fill[, mask, bandinfo])

Replace Image, if empty, with fill value.

scale_values(range_min, range_max[, …])

Given an interval, band values will be scaled to the interval.

sin()

Element-wise sine of an Image.

sqrt()

Element-wise square root of an Image.

square()

Element-wise square of an Image.

std([axis])

Standard deviation along the provided axis, or across all pixels in the image if no axis argument is provided.

sum([axis])

Sum of pixel values across the provided axis, or across all pixels in the image if no axis argument is provided.

tan()

Element-wise tangent of an Image.

tile_layer([name, scales, colormap, …])

A WorkflowsLayer for this Image.

unpack_bands(bands)

Convenience method for unpacking multiple bands into Python variables.

value_at(x, y)

Given coordinates x, y, returns the pixel values from an Image in a Dict by bandname.

visualize(name[, scales, colormap, …])

Add this Image to wf.map, or replace a layer with the same name.

with_bandinfo(band, **bandinfo)

New Image, with the given **bandinfo fields added to the specified band’s bandinfo.

with_properties(**properties)

New Image, with the given **properties fields added to the Image’s properties.

without_bandinfo(band, *bandinfo_keys)

New Image, with each given *bandinfo_keys field dropped from the specified band’s bandinfo.

without_properties(*property_keys)

New Image, with each given property field name dropped from the Image’s properties field.

Attributes

bandinfo

Metadata about the bands of the Image.

nbands

The number of bands in the Image.

ndarray

MaskedArray

properties

Metadata for the Image.

>>> from descarteslabs.workflows import Image
>>> from descarteslabs.scenes import DLTile
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> img
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
>>> # create a geocontext for our computation, using DLTile
>>> geoctx = DLTile.from_latlon(35.6, -105.4, resolution=10, tilesize=512, pad=0)
>>> img.compute(geoctx) 
ImageResult:
  * ndarray: MaskedArray<shape=(27, 512, 512), dtype=float64>
  * properties: 'absolute_orbit', 'acquired', 'archived', 'area', ...
  * bandinfo: 'coastal-aerosol', 'blue', 'green', 'red', ...
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
>>>
>>> rgb = img.pick_bands("red green blue") # an Image with the red, green, and blue bands only
>>> rgb.compute(geoctx) 
ImageResult:
  * ndarray: MaskedArray<shape=(3, 512, 512), dtype=float64>
  * properties: 'absolute_orbit', 'acquired', 'archived', 'area', ...
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
>>> rgb.min(axis="pixels").compute(geoctx) # min along the pixels axis 
{'red': 0.0329, 'green': 0.0461, 'blue': 0.0629}
arccos()[source]

Element-wise inverse cosine of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.arccos().compute(geoctx) 
ImageResult:
...
arcsin()[source]

Element-wise inverse sine of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.arcsin().compute(geoctx) 
ImageResult:
...
arctan()[source]

Element-wise inverse tangent of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.arctan().compute(geoctx) 
ImageResult:
...
clip_values(min=None, max=None)[source]

Given an interval, band values outside the interval are clipped to the interval edge.

If the Image is empty, returns the empty Image.

Parameters
  • min (float or list, default None) – Minimum value of clipping interval. If None, clipping is not performed on the lower interval edge.

  • max (float or list, default None) – Maximum value of clipping interval. If None, clipping is not performed on the upper interval edge. Different per-band clip values can by given by using lists for min or max, in which case they must be the same length as the number of bands.

  • Note (min and max cannot both be None. At least one must be specified.) –

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> img.compute(geoctx).ndarray 
masked_array(
  data=[[[0.34290000000000004, 0.34290000000000004, 0.34290000000000004,
                ..., 0.0952, 0.0952, 0.0952],
...
>>> clipped = img.clip_values(0.08, 0.3).compute(geoctx) 
>>> clipped.ndarray 
masked_array(
  data=[[[0.3, 0.3, 0.3, ..., 0.0952, 0.0952, 0.0952],
...
colormap(named_colormap='viridis', vmin=None, vmax=None)[source]

Apply a colormap to an Image. Image must have a single band.

If the Image is empty, returns the empty Image.

Parameters
  • named_colormap (Str, default "viridis") – The name of the Colormap registered with matplotlib. See https://matplotlib.org/users/colormaps.html for colormap options.

  • vmin (float, default None) – The minimum value of the range to normalize the bands within. If specified, vmax must be specified as well.

  • vmax (float, default None) – The maximum value of the range to normalize the bands within. If specified, vmin must be specified as well.

  • Note (If neither vmin nor vmax are specified, the min and max values in the Image will be used.) –

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.pick_bands("red").colormap("magma", vmin=0.1, vmax=0.8).compute(geoctx) 
ImageResult:
...
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

concat(*imgs)[source]

ImageCollection with imgs concatenated onto this Image, where imgs is a variable number of Image or ImageCollection objects.

Images, properties, and bandinfo are concatenated. All imagery must have the same number of bands with identical names. Any empty Images or ImageCollections will not be concatenated.

Parameters

*imgs (variable number of Image or ImageCollection objects) –

Returns

concatenated

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.concat(img, img).compute(geoctx) 
ImageCollectionResult of length 3:
...
concat_bands(other_image)[source]

New Image, with the bands in other_image appended to this one.

If band names overlap, the band from the other Image will be suffixed with “_1”.

If either Image is empty, returns another empty Image.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> red = img.pick_bands("red")
>>> green = img.pick_bands("green")
>>> rg = red.concat_bands(green).compute(geoctx) 
>>> rg.bandinfo.keys() 
['red', 'green']
coords_to_index(x, y)[source]

Convert spatial coordinates (x, y) to pixel coordinates (row, col) in the Image.

Parameters

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue") # an Image with the red, green, and blue bands only
>>> rgb.index(0, 0).compute(ctx) 
(459040.0, 3942400.0)
cos()[source]

Element-wise cosine of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.cos().compute(geoctx) 
ImageResult:
...
count(axis=None)[source]

Count of valid (unmasked) pixels across the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the valid pixel count.

Options:

  • "pixels": Returns a Dict[Str, Float] containing the count of valid pixels in each band.

  • "bands": Returns a new Image with one band, "count", containing the count of valid pixels across all bands, for each pixel.

  • None: Returns a Float that represents the count of valid pixels in the image.

Returns

Count of valid pixels across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> count_img = img.count(axis="bands")
>>> band_counts = img.count(axis="pixels")
>>> count = img.count(axis=None)
exp()[source]

Element-wise exponential of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.exp().compute(geoctx) 
ImageResult:
...
classmethod from_id(image_id, resampler=None, processing_level=None)[source]

Create a proxy Image from an ID in the Descartes Labs catalog.

Parameters
  • image_id (Str) – ID of the image

  • resampler (Str, optional, default None) – Algorithm used to interpolate pixel values when scaling and transforming the image to the resolution and CRS eventually defined by a GeoContext. Possible values are near (nearest-neighbor), bilinear, cubic, cubicspline, lanczos, average, mode, max, min, med, q1, q3.

  • processing_level (Str, optional) – Reflectance processing level. Possible values are 'toa' (top of atmosphere) and 'surface'. For products that support it, 'surface' applies Descartes Labs’ general surface reflectance algorithm to the output.

Returns

img

Return type

Image

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1", processing_level="surface")
>>> img.compute(geoctx) 
ImageResult:
...
classmethod from_scene(scene)[source]

Create a proxy image from a Scene object

getmask()[source]

Mask of this Image, as a new Image with one boolean band named 'mask'.

If the Image is empty, returns the empty Image.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> mask = img.getmask().compute(geoctx) 
>>> mask.ndarray 
masked_array(
  data=[[[0, 0, 0, ..., 1, 1, 1],
...
>>> mask.bandinfo 
{'mask': {}}
index_to_coords(row, col)[source]

Convert pixel coordinates (row, col) in the ImageCollection into spatial coordinates (x, y).

Parameters
  • row (int) – The row

  • col (int) – The col

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue") # an Image with the red, green, and blue bands only
>>> rgb.index(0, 0).compute(ctx) 
(459040.0, 3942400.0)
inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

log()[source]

Element-wise natural log of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.log().compute(geoctx) 
ImageResult:
...
log10()[source]

Element-wise base 10 log of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.log10().compute(geoctx) 
ImageResult:
...
log1p()[source]

Element-wise log of 1 + an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.log1p().compute(geoctx) 
ImageResult:
...
log2()[source]

Element-wise base 2 log of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.log2().compute(geoctx) 
ImageResult:
...
map_bands(func)

Map a function over each band in self.

The function must take 2 arguments:

  1. Str: the band name

  2. Image: 1-band Image

If the function returns an Image, map_bands will also return one Image, containing the bands from all Images returned by func concatenated together.

Otherwise, map_bands will return a Dict of the results of each call to func, where the keys are the band names.

Note that func can return Images with more than 1 band, but the band names must be unique across all of its results.

Parameters

func (Python function) – Function that takes a Str and an Image.

Returns

  • Image if func returns Image, otherwise Dict[Str, T],

  • where T is the return type of func.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> mapped = img.map_bands(lambda name, band: band / 2) # divide each band by 2
mask(mask, replace=False)[source]

New Image, masked with a boolean Image or vector object.

If the mask is empty, the original Image is returned unchanged. (If the Image was already empty, it is still empty even if the mask is non-empty.)

Parameters
  • mask (Image, Geometry, Feature, FeatureCollection) –

    A single-band Image of boolean values, (such as produced by img > 2, for example) where True means masked (invalid).

    Or, a vector (Geometry, Feature, or FeatureCollection), in which case pixels outside the vector are masked.

  • replace (Bool, default False) – If False (default), adds this mask to the current one, so already-masked pixels remain masked, or replaces the current mask with this new one if True.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> red = img.pick_bands("red")
>>> masked = red.mask(red < 0.2) # mask all bands where red band is low
max(axis=None)[source]

Maximum pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the maximum.

Options:

  • "pixels": Returns a Dict[Str, Float] of each band’s maximum pixel value.

  • "bands": Returns a new Image with one band, "max", containing the maximum value for each pixel across all bands.

  • None: Returns a Float that represents the maximum pixel value of the entire image.

Returns

Maximum pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> max_img = img.max(axis="bands")
>>> band_maxs = img.max(axis="pixels")
>>> max_pixel = img.max(axis=None)
mean(axis=None)[source]

Mean pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the mean.

Options:

  • "pixels": Returns a Dict[Str, Float] of each band’s mean pixel value.

  • "bands": Returns a new Image with one band, "mean", containing the mean value for each pixel across all bands.

  • None: Returns a Float that represents the mean pixel value of the entire image.

Returns

Mean pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> mean_img = img.mean(axis="bands")
>>> band_means = img.mean(axis="pixels")
>>> mean_pixel = img.mean(axis=None)
median(axis=None)[source]

Median pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the median.

Options:

  • "pixels": Returns a Dict[Str, Float] of each band’s median pixel value.

  • "bands": Returns a new Image with one band, "median", containing the median value for each pixel across all bands.

  • None: Returns a Float that represents the median pixel value of the entire image.

Returns

Median pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> median_img = img.median(axis="bands")
>>> band_medians = img.median(axis="pixels")
>>> median_pixel = img.median(axis=None)
min(axis=None)[source]

Minimum pixel value across the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the minimum.

Options:

  • "pixels": Returns a Dict[Str, Float] of each band’s minimum pixel value.

  • "bands": Returns a new Image with one band, "min", containing the minimum value for each pixel across all bands.

  • None: Returns a Float that represents the minimum pixel value of the entire image.

Returns

Minimum pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> min_img = img.min(axis="bands")
>>> band_mins = img.min(axis="pixels")
>>> min_pixel = img.min(axis=None)
pick_bands(bands, allow_missing=False)

New Image, containing only the given bands.

Bands can be given as a sequence of strings, or a single space-separated string (like "red green blue").

Bands on the new Image will be in the order given.

If names are duplicated, repeated names will be suffixed with _N, with N incrementing from 1 for each duplication (pick_bands("red red red") returns bands named red red_1 red_2).

If the Image is empty, returns the empty Image.

If allow_missing is False (default), raises an error if given band names that don’t exist in the Image. If allow_missing is True, any missing names are dropped, and if none of the names exist, returns an empty Image.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> rgb.bandinfo.keys().inspect(ctx)  
["red", "green", "blue"]
>>> red = img.pick_bands(["red", "nonexistent_band_name"], allow_missing=True)
>>> red.bandinfo.keys().inspect(ctx)  
["red"]
>>> s1_img = Image.from_id("sentinel-1:GRD:meta_2020-06-09_049A0903_S1B")
>>> vv_vh_vv = s1_img.pick_bands("vv vh vv")
>>> vv_vh_vv.bandinfo.keys().inspect(ctx)  
["vv", "vh", "vv_1"]
publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

rename_bands(*new_positional_names, **new_names)

New Image, with bands renamed by position or name.

New names can be given positionally (like rename_bands('new_red', 'new_green')), which renames the i-th band to the i-th argument.

Or, new names can be given by keywords (like rename_bands(red="new_red")) mapping from old band names to new ones.

To eliminate ambiguity, names cannot be given both ways.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> renamed = img.rename_bands(red="new_red", blue="new_blue", green="new_green")
replace_empty_with(fill, mask=True, bandinfo=None)[source]

Replace Image, if empty, with fill value.

Parameters
  • fill (int, float, Image) – The value to fill the Image with. If int or float, the fill value will be broadcasted to band dimensions as determined by the geocontext and provided bandinfo.

  • mask (bool, default True) – Whether to mask the band data. If mask is True and fill is an Image, the original Image mask will be overridden and all underlying data will be masked. If mask is False and fill is an Image, the original mask is left as is. If fill is scalar, the Image constructed will be fully masked or fully un-masked data if mask is True and False respectively.

  • bandinfo (dict, default None) – Bandinfo used in constructing new Image. If fill is an Image, bandinfo is optional, and will be ignored if provided. If fill is a scalar, the bandinfo will be used to determine the number of bands on the new Image, as well as become the bandinfo for it.

Example

>>> from descarteslabs.workflows import Image
>>> empty_img = Image.from_id("id_without_surface_reflectance", processing_level="surface") 
>>> empty_img.compute(geoctx) 
EmptyImage
>>> non_empty = empty_img.replace_empty_with(9999, bandinfo={"red":{}, "green":{}, "blue":{}}) 
>>> non_empty.compute(geoctx) 
ImageResult:
  * ndarray: MaskedArray<shape=(3, 512, 512), dtype=float64>
  * properties:
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
scale_values(range_min, range_max, domain_min=None, domain_max=None)[source]

Given an interval, band values will be scaled to the interval.

If the Image is empty, returns the empty Image.

Parameters
  • range_min (float) – Minimum value of output range.

  • range_max (float) – Maximum value of output range.

  • domain_min (float, default None) – Minimum value of the domain. If None, the band minimim is used.

  • domain_max (float, default None) – Maximum value of the domain. If None, the band maximum is used.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> img.compute(geoctx).ndarray 
masked_array(
  data=[[[0.34290000000000004, 0.34290000000000004, 0.34290000000000004, ...,
...
>>> scaled = img.scale_values(0.5, 1).compute(geoctx) 
>>> scaled.ndarray 
masked_array(
  data=[[[0.500010245513916, 0.500010245513916, 0.500010245513916, ...,
...
sin()[source]

Element-wise sine of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.sin().compute(geoctx) 
ImageResult:
...
sqrt()[source]

Element-wise square root of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.sqrt().compute(geoctx) 
ImageResult:
...
square()[source]

Element-wise square of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.square().compute(geoctx) 
ImageResult:
...
std(axis=None)[source]

Standard deviation along the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the standard deviation.

Options:

  • "pixels": Returns a Dict[Str, Float] containing the standard deviation across each band.

  • "bands": Returns a new Image with one band, "std", containing the standard deviation across all bands for each pixel.

  • None: Returns a Float that represents the standard deviation of the entire image.

Returns

Standard deviation along the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> std_img = img.std(axis="bands")
>>> band_stds = img.std(axis="pixels")
>>> std = img.std(axis=None)
sum(axis=None)[source]

Sum of pixel values across the provided axis, or across all pixels in the image if no axis argument is provided.

If the Image is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "pixels", "bands"}) –

A Python string indicating the axis along which to take the sum.

Options:

  • "pixels": Returns a Dict[Str, Float] containing the sum of the pixel values for each band.

  • "bands": Returns a new Image with one band, "sum", containing the sum across all bands for each pixel.

  • None: Returns a Float that represents the sum of all pixels in the image.

Returns

Sum of pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float] or Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:01:RT:TOAR:meta_LC08_L1TP_033035_20170516_20170516_01_RT_v1")
>>> sum_img = img.sum(axis="bands")
>>> band_sums = img.sum(axis="pixels")
>>> sum_pixels = img.sum(axis=None)
tan()[source]

Element-wise tangent of an Image.

If the Image is empty, returns the empty Image.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> img.tan().compute(geoctx) 
ImageResult:
...
tile_layer(name=None, scales=None, colormap=None, checkerboard=True, **parameters)[source]

A WorkflowsLayer for this Image.

Generally, use Image.visualize for displaying on map. Only use this method if you’re managing your own ipyleaflet Map instances, and creating more custom visualizations.

An empty Image will be rendered as a checkerboard (default) or blank tile.

Parameters
  • name (str) – The name of the layer.

  • scales (list of lists, default None) –

    The scaling to apply to each band in the Image.

    If Image contains 3 bands, scales must be a list like [(0, 1), (0, 1), (-1, 1)].

    If Image contains 1 band, scales must be a list like [(0, 1)], or just (0, 1) for convenience

    If None, each 256x256 tile will be scaled independently. based on the min and max values of its data.

  • colormap (str, default None) – The name of the colormap to apply to the Image. Only valid if the Image has a single band.

  • checkerboard (bool, default True) – Whether to display a checkerboarded background for missing or masked data.

  • **parameters (JSON-serializable value, Proxytype, or ipywidgets.Widget) –

    Runtime parameters to use when computing tiles. Values can be any JSON-serializable value, a Proxytype instance, or an ipywidgets Widget.

    See the docstring for visualize for more detail.

Returns

layer

Return type

WorkflowsLayer

unpack_bands(bands)

Convenience method for unpacking multiple bands into Python variables.

Returns a Python tuple of self.pick_bands called for each band name. Bands can be given as a space-separated string of band names, or a sequence.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> red, green, blue = img.unpack_bands("red green blue")
value_at(x, y)[source]

Given coordinates x, y, returns the pixel values from an Image in a Dict by bandname.

Coordinates must be given in the same coordinate reference system as the GeoContext you call compute with. For example, if your GeoContext uses "EPSG:4326", you’d give x and y in lon, lat degrees. If your GeoContext uses UTM, you’d give x and y in UTM coordinates.

When using visualize to view the Image on a map, x and y must always be given in web-mercator ("EPSG:3857") coordinates (with units of meters, not degrees).

If the Image is empty, returns an empty Dict.

Parameters

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue") # an Image with the red, green, and blue bands only
>>> rgb.value_at(459040.0, 3942400.0) 
'{red': 0.39380000000000004
'green': 0.40950000000000003,
'blue': 0.44870000000000004}
visualize(name, scales=None, colormap=None, checkerboard=True, map=None, **parameters)[source]

Add this Image to wf.map, or replace a layer with the same name.

An empty Image will be rendered as a checkerboard (default) or blank tile.

Parameters
  • name (str) –

    The name of the layer.

    If a layer with this name already exists on wf.map, it will be replaced with this Image, scales, and colormap. This allows you to re-run cells in Jupyter calling visualize without adding duplicate layers to the map.

  • scales (list of lists, default None) –

    The scaling to apply to each band in the Image.

    If Image contains 3 bands, scales must be a list like [(0, 1), (0, 1), (-1, 1)].

    If Image contains 1 band, scales must be a list like [(0, 1)], or just (0, 1) for convenience

    If None, each 256x256 tile will be scaled independently. based on the min and max values of its data.

  • colormap (str, default None) – The name of the colormap to apply to the Image. Only valid if the Image has a single band.

  • checkerboard (bool, default True) – Whether to display a checkerboarded background for missing or masked data.

  • map (Map or MapApp, optional, default None) – The Map (or plain ipyleaflet Map) instance on which to show the Image. If None (default), uses wf.map, the singleton Workflows MapApp object.

  • **parameters (JSON-serializable value, Proxytype, or ipywidgets.Widget) –

    Runtime parameters to use when computing tiles. Values can be any JSON-serializable value, a Proxytype instance, or an ipywidgets Widget.

    Once these initial parameter values are set, they can be modified by assigning to parameters on the returned WorkflowsLayer.

    If a Widget is given, it’s automatically linked, so updating the widget causes the parameter value to change, and the map to update. Running visualize again and passing in a different widget instance will un-link the old one automatically.

    If a Python value or Proxytype is given, values you later assign to that parameter must be of a compatible type (for example, you can’t give threshold=0.6, then assign lyr.parameters.threshold = "foo", because "foo" can’t be cast to a float).

    For more information, see the docstring to ParameterSet.

Returns

layer – The layer displaying this Image. Either a new WorkflowsLayer if one was created, or the layer with the same name that was already on the map.

Return type

WorkflowsLayer

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> nir, red = col.unpack_bands(["nir", "red"])
>>> ndvi = wf.normalized_difference(nir, red)
>>> max_ndvi = ndvi.max()
>>> highest_ndvi = max_ndvi > wf.parameter("threshold", wf.Float)
>>> lyr = highest_ndvi.visualize(
...     name="My Cool Max NDVI",
...     scales=[0, 1],
...     colormap="viridis",
...     threshold=0.4,
... )  
>>> wf.map  
>>> # `wf.map` actually displays the map; right click and open in new view in JupyterLab
>>> lyr.parameters.threshold = 0.3  
>>> # update map with a new value for the "threshold" parameter
with_bandinfo(band, **bandinfo)[source]

New Image, with the given **bandinfo fields added to the specified band’s bandinfo.

If a given field already exists on the band’s bandinfo, it will be overwritten.

If the Image is empty, returns the empty Image.

Parameters
  • band (Str) – The name of the band whose bandinfo will be added to.

  • **bandinfo (dict) – Fields that will be added to the band’s bandinfo

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> with_foo = img.with_bandinfo("red", foo="baz").compute(geoctx) 
>>> with_foo.bandinfo["red"]["foo"] 
'baz'
with_properties(**properties)[source]

New Image, with the given **properties fields added to the Image’s properties.

If a given field already exists on the Image’s properties, it will be overwritten.

If the Image is empty, returns the empty Image.

Parameters

**properties (Proxytype, or any JSON-serializable value) – Fields that will be added to the image’s properties

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> with_foo = img.with_properties(foo="baz").compute(geoctx) 
>>> with_foo.properties["foo"] 
'baz'
without_bandinfo(band, *bandinfo_keys)[source]

New Image, with each given *bandinfo_keys field dropped from the specified band’s bandinfo.

If a given field doesn’t exists on the band’s bandinfo, it will be a no-op.

Parameters
  • band (Str) – The name of the band whose bandinfo will be pruned.

  • *bandinfo_keys (Str) – Fields that will be dropped from the band’s bandinfo

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.compute(geoctx).bandinfo["red"] 
{'color': 'Red',
 'data_description': 'TOAR, 0-10000 is 0 - 100% reflective',
...
>>> without_desc = img.without_bandinfo("red", "data_description").compute(geoctx) 
>>> without_desc.bandinfo["red"] 
{'color': 'Red',
 'data_range': [0, 10000],
...
without_properties(*property_keys)[source]

New Image, with each given property field name dropped from the Image’s properties field.

If a given field doesn’t exist on the Image’s properties, it will be a no-op.

Parameters

*properties_keys (Str) – Fields that will be dropped from the image’s properties

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.compute(geoctx).properties 
{'acquired': '2016-07-06T16:59:42.753476+00:00',
 'area': 35619.4,
...
>>> without_acq = img.without_properties("acquired").compute(geoctx) 
>>> without_acq.properties 
{'area': 35619.4,
 'bits_per_pixel': [0.836, 1.767, 0.804],
...
property bandinfo

Metadata about the bands of the Image.

bandinfo is a Dict, where keys are band names and values are Dicts which always contain these fields:

  • id (Str): the Descartes Labs ID of the band

  • name (Str): the name of the band. Equal to the key the Dict is stored under in bandinfo

  • data_range (Tuple): The (min, max) values the original data had. However, data in Images is automatically rescaled to physical range, or [0, 1] if physical range is undefined, so it won’t be in data_range anymore.

Accessing other fields will return instances of Any. Accessing fields that don’t actually exist on the data is a compute-time error.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.bandinfo['red']['data_range']
<descarteslabs.workflows.types.containers.tuple_.Tuple[Float, Float] object at 0x...>
>>> img.bandinfo['red']['foobar']  # almost certainly a compute-time error
<descarteslabs.workflows.types.primitives.any_.Any object at 0x...>
>>> img.bandinfo['foobar']['id']  # also likely a compute-time error
<descarteslabs.workflows.types.primitives.string.Str object at 0x...>
Type

Dict[Str, KnownDict[dict(data_range=Tuple[Float, Float], id=Str, name=Str), Str, Any]]

property nbands

The number of bands in the Image.

If the Image is empty, returns 0.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.nbands.compute(geoctx) 
25
property ndarray

MaskedArray

property properties

Metadata for the Image.

properties is a Dict which always contains these fields:

  • id (Str): the Descartes Labs ID of the Image

  • product (Str): the Descartes Labs ID of the product the Image belogs to

  • date (Datetime): the UTC date the Image was acquired

  • crs (Str): the original Coordinate Reference System of the Image

  • geotrans (Tuple): The original 6-tuple GDAL geotrans for the Image.

Accessing other fields will return instances of Any. Accessing fields that don’t actually exist on the data is a compute-time error.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> img.properties['date']
<descarteslabs.workflows.types.datetimes.datetime_.Datetime object at 0x...>
>>> img.properties['date'].year
<descarteslabs.workflows.types.primitives.number.Int object at 0x...>
>>> img.properties['id']
<descarteslabs.workflows.types.primitives.string.Str object at 0x...>
>>> img.properties['foobar']  # almost certainly a compute-time error
<descarteslabs.workflows.types.primitives.any_.Any object at 0x...>
Type

KnownDict[dict(crs=Str, date=Datetime, geotrans=Tuple[Float, Float, Float, Float, Float, Float], id=Str, product=Str), Str, Any]

class ImageCollection(images)[source]

Proxy object representing a stack of Images; typically construct with from_id.

An ImageCollection is a proxy object holding multiple images, each with the same (ordered) bands of raster data, plus metadata about each Image.

ImageCollections don’t have a set spatial extent, CRS, resolution, etc: that’s determined at computation time by the GeoContext passsed in.

Supports unary operations such as negation and absolute value, as well as arithmetic and comparison operators such as >, +, and //.

Examples

Methods

arccos()

Element-wise inverse cosine of an ImageCollection.

arcsin()

Element-wise inverse sine of an ImageCollection.

arctan()

Element-wise inverse tangent of an ImageCollection.

clip_values([min, max])

Given an interval, band values outside the interval are clipped to the interval edge.

colormap([named_colormap, vmin, vmax])

Apply a colormap to an ImageCollection.

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

concat(*imgs)

ImageCollection with imgs concatenated onto this one, where

concat_bands(other)

New ImageCollection, with the bands in other appended to this one.

contains(other)

Contains is equivalient to the Python in operator.

coords_to_index(x, y)

Convert spatial coordinates (x, y) to pixel coordinates (row, col) in the ImageCollection.

cos()

Element-wise cosine of an ImageCollection.

count([axis])

Count of valid (unmasked) pixels across the provided axis, or across all pixels in the ImageCollection if no axis argument is provided.

exp()

Element-wise exponential of an ImageCollection.

filter(func)

Filter elements from an iterable proxytype.

from_id(product_id[, start_datetime, …])

Create a proxy ImageCollection representing an entire product in the Descartes Labs catalog.

getmask()

Mask of this ImageCollection, as a new ImageCollection with one boolean band named ‘mask’.

groupby([func, dates])

Group the ImageCollection by a key value for each Image.

head(n)

ImageCollection of the first n Images.

index_to_coords(row, col)

Convert pixel coordinates (row, col) in the ImageCollection into spatial coordinates (x, y).

inspect([geoctx, format, file, timeout, client])

Quickly compute this proxy object using a low-latency, lower-reliability backend.

length()

Length is equivalent to the Python len operator.

log()

Element-wise natural log of an ImageCollection.

log10()

Element-wise base 10 log of an ImageCollection.

log1p()

Element-wise log of 1 + an ImageCollection.

log2()

Element-wise base 2 log of an ImageCollection.

map(func)

Map a function over the Images in an ImageCollection.

map_bands(func)

Map a function over each band in self.

map_window(func[, back, fwd])

Map a function over a sliding window of this ImageCollection.

mask(mask[, replace])

New ImageCollection, masked with a boolean ImageCollection, Image, or vector object.

max([axis])

Maximum pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

mean([axis])

Mean pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

median([axis])

Median pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

min([axis])

Minimum pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

mosaic([reverse])

Composite the ImageCollection into a single Image by picking each first-unmasked pixel.

partition(i)

Split this ImageCollection into two collections at index i.

pick_bands(bands[, allow_missing])

New ImageCollection, containing Images with only the given bands.

publish(id, version[, title, description, …])

Publish this proxy object as a Workflow version.

reduce(func[, initial])

Reduce a collection of elements to a single element.

rename_bands(*new_positional_names, **new_names)

New ImageCollection, with bands renamed by position or name.

replace_empty_with(fill[, mask, bandinfo])

Replace ImageCollection, if empty, with fill value.

scale_values(range_min, range_max[, …])

Given an interval, band values will be scaled to the interval.

sin()

Element-wise sine of an ImageCollection.

sortby_composite(band[, operation])

Sort-by composite of an ImageCollection Creates a composite of an ImageCollection using the argmin or argmax of a specified band as the per-pixel ordering.

sorted(key[, reverse])

Copy of this ImageCollection, sorted by a key function.

sqrt()

Element-wise square root of an ImageCollection.

square()

Element-wise square of an ImageCollection.

std([axis])

Standard deviation along the provided axis, or across all pixels in the image collection if no axis argument is provided.

sum([axis])

Sum of pixel values across the provided axis, or across all pixels in the image collection if no axis argument is provided.

tail(n)

ImageCollection of the last n Images.

tan()

Element-wise tangent of an ImageCollection.

unpack_bands(bands)

Convenience method for unpacking multiple bands into Python variables.

value_at(x, y)

Given coordinates x, y, returns the pixel values from an ImageCollection in a List[Dict] by bandname.

with_bandinfo(band, **bandinfo)

New ImageCollection, with the given **bandinfo fields added to the specified band’s bandinfo.

without_bandinfo(band, *bandinfo_keys)

New ImageCollection, with each given *bandinfo_keys field dropped from the specified band’s bandinfo.

Attributes

bandinfo

Metadata about the bands of the ImageCollection.

nbands

The number of bands in the ImageCollection.

ndarray

MaskedArray

properties

Metadata for each Image in the ImageCollection.

>>> from descarteslabs.workflows import ImageCollection
>>> from descarteslabs.scenes import DLTile
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-12-31")
>>> col
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> # create a geocontext for our computation, using DLTile
>>> geoctx = DLTile.from_latlon(10, 30, resolution=10, tilesize=512, pad=0)
>>> col.compute(geoctx) 
ImageCollectionResult of length 14:
  * ndarray: MaskedArray<shape=(14, 27, 512, 512), dtype=float64>
  * properties: 14 items
  * bandinfo: 'coastal-aerosol', 'blue', 'green', 'red', ...
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
>>>
>>> rgb = col.pick_bands("red green blue") # an ImageCollection with the red, green, and blue bands only
>>> rgb.compute(geoctx) 
ImageCollectionResult of length 14:
  * ndarray: MaskedArray<shape=(14, 3, 512, 512), dtype=float64>
  * properties: 14 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
>>> rgb.max(axis=("images", "pixels")).compute(geoctx) # max along the images then pixels axis 
{'red': 0.8074, 'green': 0.7857000000000001, 'blue': 0.8261000000000001}

Construct an ImageCollection from a sequence of Images.

Will return an empty ImageCollection if given an empty list or a list of empty images. If given a list of some non-empty and some empty images, the empties will be dropped.

arccos()[source]

Element-wise inverse cosine of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.arccos().compute(geoctx) 
ImageCollectionResult of length 2:
...
arcsin()[source]

Element-wise inverse sine of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.arcsin().compute(geoctx) 
ImageCollectionResult of length 2:
...
arctan()[source]

Element-wise inverse tangent of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.arctan().compute(geoctx) 
ImageCollectionResult of length 2:
...
clip_values(min=None, max=None)[source]

Given an interval, band values outside the interval are clipped to the interval edge.

If the ImageCollection is empty, returns the empty ImageCollection.

Parameters
  • min (float or list, default None) – Minimum value of clipping interval. If None, clipping is not performed on the lower interval edge.

  • max (float or list, default None) – Maximum value of clipping interval. If None, clipping is not performed on the upper interval edge. Different per-band clip values can be given by using lists for min or max, in which case they must be the same length as the number of bands.

  • Note (min and max cannot both be None. At least one must be specified.) –

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.compute(geoctx).ndarray 
masked_array(
  data=[[[[0.1578, 0.1578, 0.1578, ..., 0.13920000000000002, 0.1376,
                 0.1376],
...
>>> clipped = col.clip_values(0.14, 0.3).compute(geoctx) 
>>> clipped.ndarray 
masked_array(
  data=[[[[0.1578, 0.1578, 0.1578, ..., 0.14, 0.14, 0.14],
...
colormap(named_colormap='viridis', vmin=None, vmax=None)[source]

Apply a colormap to an ImageCollection. Each image must have a single band.

If the ImageCollection is empty, returns the empty ImageCollection.

Parameters
  • named_colormap (Str, default "viridis") – The name of the Colormap registered with matplotlib. See https://matplotlib.org/users/colormaps.html for colormap options.

  • vmin (float, default None) – The minimum value of the range to normalize the bands within. If specified, vmax must be specified as well.

  • vmax (float, default None) – The maximum value of the range to normalize the bands within. If specified, vmin must be specified as well.

  • Note (If neither vmin nor vmax are specified, the min and max values in each Image will be used.) –

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.pick_bands("red").colormap("magma", vmin=0.1, vmax=0.8).compute(geoctx) 
ImageCollectionResult of length 2:
  * ndarray: MaskedArray<shape=(2, 3, 512, 512), dtype=float64>
  * properties: 2 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • destination (str or dict, default "download") –

    The destination for the result. See the destinations documentation for more information.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises JobTimeoutError if the timeout passes.

  • block (bool, default True) – If True (default), block until the job is completed, or timeout has passed. If False, immediately returns a Job (which has already had execute called).

  • progress_bar (bool, default None) – Whether to draw the progress bar. If None (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if block==False.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None

Return type

Python object, bytes, or None

concat(*imgs)[source]

ImageCollection with imgs concatenated onto this one, where imgs is a variable number of Image or ImageCollection objects.

Images, properties, and bandinfo are concatenated. All imagery must have the same number of bands with identical names. Any empty Images or ImageCollections will not be concatenated.

Parameters

*imgs (variable number of Image or ImageCollection objects) –

Returns

concatenated

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.concat(col, col).compute(geoctx) 
ImageCollectionResult of length 6:
...
concat_bands(other)[source]

New ImageCollection, with the bands in other appended to this one.

If band names overlap, the band name from other will be suffixed with “_1”.

If the ImageCollection is empty, or other is empty, an empty is returned (following broadcasting rules).

Parameters

other (Image, ImageCollection) –

If other is a single Image, its bands will be added to every image in this ImageCollection.

If other is an ImageCollection, it must be the same length as self.

Returns

concatenated

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> red = col.pick_bands("red")
>>> green = col.pick_bands("green")
>>> rg = red.concat_bands(green).compute(geoctx) 
>>> rg.bandinfo.keys() 
['red', 'green']
contains(other)

Contains is equivalient to the Python in operator.

Parameters

other (Proxytype) – A Proxytype or type that can be promoted to a Proxytype

Returns

A Bool Proxytype

Return type

Bool

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 2, 3])
>>> my_list.contains(2).compute() 
True
coords_to_index(x, y)[source]

Convert spatial coordinates (x, y) to pixel coordinates (row, col) in the ImageCollection.

Parameters

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.coords_to_index(459040.0, 3942400.0).compute(ctx) 
(0, 0)
cos()[source]

Element-wise cosine of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.cos().compute(geoctx) 
ImageCollectionResult of length 2:
...
count(axis=None)[source]

Count of valid (unmasked) pixels across the provided axis, or across all pixels in the ImageCollection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the valid pixel count.

Options:

  • "images": Returns an Image containing the count of valid pixels across all scenes for each pixel in each band (i.e., a temporal count composite.)

  • "bands": Returns a new ImageCollection with one band, "count", containing the count of valid pixels across all bands for each pixel and each scene.

  • "pixels": Returns a List[Dict[Str, Float]] containing the count of valid pixels in each band in each scene.

  • None: Returns a Float that represents the valid pixel count for the entire ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] containing the count of valid pixels in each band across all scenes, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] contianing the count of valid pixels in each scene across all bands.

  • ("images", "bands"): Returns an Image containing the count of valid pixels across all scenes and bands.

Returns

Count of valid pixels across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> count_composite = col.count(axis="images")
>>> count_col = col.count(axis="bands")
>>> band_counts_per_scene = col.count(axis="pixels")
>>> scene_counts = col.count(axis=("bands", "pixels"))
>>> band_counts = col.count(axis=("images", "pixels"))
>>> count = col.count(axis=None)
exp()[source]

Element-wise exponential of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.exp().compute(geoctx) 
ImageCollectionResult of length 2:
...
filter(func)

Filter elements from an iterable proxytype.

Parameters

func (Python callable) – A function that takes a single argument and returns a Bool Proxytype.

Returns

A Proxytype of the same type having only the elements where func returns True.

Return type

Proxtype

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("sentinel-2:L1C")
>>> filtered = col.filter(lambda img: img.properties["date"].year == 2018)
classmethod from_id(product_id, start_datetime=None, end_datetime=None, limit=None, resampler=None, processing_level=None)[source]

Create a proxy ImageCollection representing an entire product in the Descartes Labs catalog.

This ImageCollection represents every Image in the product, everywhere. But when a GeoContext is supplied at computation time (either by passing one into compute, or implicitly from the map view area when using Image.visualize), the actual metadata lookup and computation only happens within that area of interest.

Note there are two ways of filtering dates: using the start_datetime and end_datetime arguments here, and calling filter (like imgs.filter(lambda img: img.properties['date'].month > 5)). We recommend using start_datetime and end_datetime for giving a coarse date window (at the year level, for example), then using filter to do more sophisticated filtering within that subset if necessary.

The ImageCollection is sorted by date, in ascending order (older Images come first).

If no imagery is found to satisfy the constraints, an empty ImageCollection is returned.

Parameters
  • product_id (Str) – ID of the product

  • start_datetime (Datetime or None, optional, default None) – Restrict the ImageCollection to Images acquired after this timestamp.

  • end_datetime (Datetime or None, optional, default None) – Restrict the ImageCollection to Images before after this timestamp.

  • limit (Int or None, optional, default None) – Maximum number of Images to include. If None (default), uses the Workflows default of 10,000. Note that specifying no limit is not supported.

  • resampler (Str, optional, default None) – Algorithm used to interpolate pixel values when scaling and transforming the image to the resolution and CRS eventually defined by a GeoContext. Possible values are near (nearest-neighbor), bilinear, cubic, cubicspline, lanczos, average, mode, max, min, med, q1, q3.

  • processing_level (Str, optional) – Reflectance processing level. Possible values are 'toa' (top of atmosphere) and 'surface'. For products that support it, 'surface' applies Descartes Labs’ general surface reflectance algorithm to the output. Any Images that have not been processed for surface reflectance are filtered out. If no Images support surface reflectance, returns an empty ImageCollection.

Returns

imgs

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30", resampler="min")
>>> col.compute(geoctx) 
ImageCollectionResult of length 2:
...
getmask()[source]

Mask of this ImageCollection, as a new ImageCollection with one boolean band named ‘mask’.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> mask = col.getmask().compute(geoctx) 
>>> mask.ndarray 
masked_array(
  data=[[[[0, 0, 0, ..., 1, 1, 1],
...
>>> mask.bandinfo 
{'mask': {}}
groupby(func=None, dates=None)[source]

Group the ImageCollection by a key value for each Image.

func must take an Image, and return which group that Image belongs to. (The return type of func can be anything; the unique values returned by func over every Image become the groups.)

For convenience, dates can be given instead as a field name, or tuple of field names, to pull from the "date" field of Image.properties.

Creates an ImageCollectionGroupby object, which can be used to aggregate the groups.

Within the ImageCollectionGroupby, every Image in every ImageCollection group also gets the field "group" added to its properties, which identifies which group it belongs to.

Type-theoretically: groupby(func: Function[Image, {}, T]) -> ImageCollectionGroupby[T]

If the ImageCollection is empty, or func results in empty groups, ImageCollectionGroupby.groups will return an empty Dict.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> # group all Images from the same year and month, then take the mean (along the 'images' axis) of each group
>>> col.groupby(dates=("year", "month")).mean(axis="images")
<descarteslabs.workflows.types.geospatial.imagecollection.ImageCollection object at 0x...>
>>> # group all Images from the same month, get Images from April, and take the median along the 'images' axis
>>> col.groupby(dates="month")[4].median(axis="images")
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
>>> # place images in 14 day bins, and take the min for each group (using a mapper function)
>>> col.groupby(lambda img: img.properties['date'] // wf.Timedelta(days=14)).map(lambda group, img: img.min())
<descarteslabs.workflows.types.containers.dict_.Dict[Datetime, Float] object at 0x...>
head(n)[source]

ImageCollection of the first n Images.

If the ImageCollection is empty, an empty ImageCollection is returned (all values of n are valid).

Parameters

n (Int) – Can be longer than the ImageCollection without error, in which case the whole ImageCollection is returned.

Returns

imgs

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.head(2).compute(geoctx) 
ImageCollectionResult of length 2:
...
index_to_coords(row, col)[source]

Convert pixel coordinates (row, col) in the ImageCollection into spatial coordinates (x, y).

Parameters
  • row (int) – The row

  • col (int) – The col

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.index_to_coords(0, 0).compute(ctx) 
(459040.0, 3942400.0)
inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters
  • geoctx (scenes.geocontext.GeoContext, GeoContext, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a GeoContext, but for operations that only involve non-geospatial types, this parameter is optional.

  • format (str or dict, default "pyarrow") –

    The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes.

  • file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them.

  • timeout (int, optional, default 30) – The number of seconds to wait for the result. Raises JobTimeoutError if the timeout passes.

  • client (workflows.inspect.InspectClient, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters

  • **params (Proxytype) – Parameters under which to run the computation.

Returns

result – When format="pyarrow" (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.result_types. For other formats, returns raw bytes. Consider using file in that case to save the results to a file.

Return type

Python object or bytes

length()

Length is equivalent to the Python len operator.

Returns

An Int Proxytype

Return type

Int

Example

>>> from descarteslabs.workflows import List, Int
>>> my_list = List[Int]([1, 2, 3])
>>> my_list.length().compute() 
3
log()[source]

Element-wise natural log of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.log().compute(geoctx) 
ImageCollectionResult of length 2:
...
log10()[source]

Element-wise base 10 log of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.log10().compute(geoctx) 
ImageCollectionResult of length 2:
...
log1p()[source]

Element-wise log of 1 + an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.log1p().compute(geoctx) 
ImageCollectionResult of length 2:
...
log2()[source]

Element-wise base 2 log of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.log2().compute(geoctx) 
ImageCollectionResult of length 2:
...
map(func)[source]

Map a function over the Images in an ImageCollection.

If the ImageCollection is empty, it will return an empty ImageCollection or List, according to the return type of func. If func returns some empty and some non-empty Image objects, the empties are dropped so only the non-empties are included in the resulting ImageCollection. If func returns all empty Image objects, an empty ImageCollection is returned.

Parameters

func (Python callable) – A function that takes a single Image and returns another proxytype.

Returns

mappedImageCollection if func returns Image, otherwise List[T], where T is the return type of func.

For example:

  • ic.map(lambda img: img + 1) returns an ImageCollection

  • ic.map(lambda img: img.properties["date"]) returns a List[Datetime].

Return type

ImageCollection or List

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
>>> means = col.map(lambda img: img.mean(axis="pixels"))
>>> type(means).__name__
'List[Dict[Str, Float]]'
>>> mean_col = col.map(lambda img: img.mean(axis="bands"))
>>> type(mean_col).__name__
'ImageCollection'
map_bands(func)[source]

Map a function over each band in self.

The function must take 2 arguments:

  1. Str: the band name

  2. ImageCollection: 1-band ImageCollection

If the function returns an ImageCollection, map_bands will also return one ImageCollection, containing the bands from all ImageCollections returned by func concatenated together.

Otherwise, map_bands will return a Dict of the results of each call to func, where the keys are the band names.

Note that func can return ImageCollections with more than 1 band, but the band names must be unique across all of its results.

If the ImageCollection is empty, it will return an empty ImageCollection or Dict, according to the return type of func. If func produces an empty Image or ImageCollection for any band, that empty is returned. (Any band being empty propagates to all of them, because it is impossible to have some bands empty and some not.)

Parameters

func (Python function) – Function that takes a Str and an ImageCollection.

Returns

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> band_means = col.mean(axis=("images", "pixels"))
>>> deviations = col.map_bands(lambda name, imgs: imgs - band_means[name])
map_window(func, back=0, fwd=0)[source]

Map a function over a sliding window of this ImageCollection.

The function must take 3 arguments:

The window slides over the ImageCollection, starting at index back and ending fwd images before the end.

Note that the total length of the window is back + 1 + fwd. Specifying a window longer than the ImageCollection will cause an error.

If the ImageCollection is empty, it will return an empty ImageCollection or List, according to the return type of func. If func returns some empty and some non-empty imagery, the empties are dropped so only the non-empties are included in the resulting ImageCollection. If func returns all empty imagery, an empty ImageCollection is returned.

Parameters
  • back (Int, optional, default 0) – Number of previous Images to pass as back to the function.

  • fwd (Int, optional, default 0) – Number of subsequent Images to pass as fwd to the function.

Returns

mapped – If func returns an ImageCollection or Image, all of them are concatenated together and returned as one ImageCollection.

Otherwise, returns a List of the values returned by func.

Return type

ImageCollection or List

Example

>>> from descarteslabs.workflows import ImageCollection, concat
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-06-30")
>>> new_col = col.map_window(lambda back, img, fwd:
...     concat(back, img, fwd).mean(axis="images").with_properties(date=img.properties['date']), back=1, fwd=1)
>>> new_col.compute(geoctx) 
ImageCollectionResult of length 2:
...
mask(mask, replace=False)[source]

New ImageCollection, masked with a boolean ImageCollection, Image, or vector object.

If the mask is empty, the original ImageCollection is returned unchanged. (If the ImageCollection was already empty, it is still empty even if the mask is non-empty.)

Parameters
  • mask (ImageCollection, Image, Geometry, Feature, FeatureCollection) –

    A single-band ImageCollection of boolean values, (such as produced by col > 2, for example) where True means masked (invalid).

    Or, single-band Image of boolean values, (such as produced by img > 2, for example) where True means masked (invalid).

    Or, a vector (Geometry, Feature, or FeatureCollection), in which case pixels outside the vector are masked.

  • replace (Bool, default False) – If False (default), adds this mask to the current one, so already-masked pixels remain masked, or replaces the current mask with this new one if True.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> red = col.pick_bands("red")
>>> masked = red.mask(red < 0.2) # mask all the bands where the red band is low
max(axis=None)[source]

Maximum pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the maximum.

Options:

  • "images": Returns an Image containing the maximum value for each pixel in each band, across all scenes (i.e., a temporal maximum composite.)

  • "bands": Returns a new ImageCollection with one band, "max", containing the maximum value for each pixel across all bands in each scene.

  • "pixels" Returns a List[Dict[Str, Float]] containing each band’s maximum pixel value for each scene in the collection.

  • None: Returns a Float that represents the maximum pixel value of the entire ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] of the maximum pixel value for each band across all scenes, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] of the maximum pixel value for each scene across all bands.

  • ("images", "bands"): Returns an Image containing the maximum value across all scenes and bands.

Returns

Maximum pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> max_composite = col.max(axis="images")
>>> max_col = col.max(axis="bands")
>>> band_maxs_per_scene = col.max(axis="pixels")
>>> scene_maxs = col.max(axis=("bands", "pixels"))
>>> band_maxs = col.max(axis=("images", "pixels"))
>>> max_pixel = col.max(axis=None)
mean(axis=None)[source]

Mean pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the mean.

Options:

  • "images": Returns an Image containing the mean value for each pixel in each band, across all scenes

  • "bands": Returns a new ImageCollection with one band, "mean", containing the mean value for each pixel across all bands in each scene.

  • "pixels" Returns a List[Dict[Str, Float]] containing each band’s mean pixel value for each scene in the collection. (i.e., a temporal mean composite.)

  • None: Returns a Float that represents the mean pixel value of the entire ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] of the mean pixel value for each band across all scenes, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] of the mean pixel value for each scene across all bands.

  • ("images", "bands"): Returns an Image containing the mean value across all scenes and bands.

Returns

Mean pixel value across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> mean_composite = col.mean(axis="images")
>>> mean_col = col.mean(axis="bands")
>>> band_means_per_scene = col.mean(axis="pixels")
>>> scene_means = col.mean(axis=("bands", "pixels"))
>>> band_means = col.mean(axis=("images", "pixels"))
>>> mean_pixel = col.mean(axis=None)
median(axis=None)[source]

Median pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the median.

Options:

  • "images": Returns an Image containing the median value for each pixel in each band, across all scenes (i.e., a temporal median composite.)

  • "bands": Returns a new ImageCollection with one band, "median", containing the median value for each pixel across all bands in each scene.

  • "pixels" Returns a List[Dict[Str, Float]] containing each band’s median pixel value for each scene in the collection.

  • None: Returns a Float that represents the median pixel value of the entire ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] of the median pixel value for each band across all scenes, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] of the median pixel value for each scene across all bands.

  • ("images", "bands"): Returns an Image containing the median value across all scenes and bands.

Returns

Median pixel value across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> median_composite = col.median(axis="images")
>>> median_col = col.median(axis="bands")
>>> band_medians_per_scene = col.median(axis="pixels")
>>> scene_medians = col.median(axis=("bands", "pixels"))
>>> band_medians = col.median(axis=("images", "pixels"))
>>> median_pixel = col.median(axis=None)
min(axis=None)[source]

Minimum pixel value across the provided axis, or across all pixels in the image collection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the minimum.

Options:

  • "images": Returns an Image containing the minimum value for each pixel in each band, across all scenes (i.e., a temporal minimum composite.)

  • "bands": Returns a new ImageCollection with one band, "min", containing the minimum value for each pixel across all bands in each scene.

  • "pixels" Returns a List[Dict[Str, Float]] containing each band’s minimum pixel value for each scene in the collection.

  • None: Returns a Float that represents the minimum pixel value of the entire ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] of the minimum pixel value for each band across all scenes, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] of the minimum pixel value for each scene across all bands.

  • ("images", "bands"): Returns an Image containing the minimum value across all scenes and bands.

Returns

Minimum pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> min_composite = col.min(axis="images")
>>> min_col = col.min(axis="bands")
>>> band_mins_per_scene = col.min(axis="pixels")
>>> scene_mins = col.min(axis=("bands", "pixels"))
>>> band_mins = col.min(axis=("images", "pixels"))
>>> min_pixel = col.min(axis=None)
mosaic(reverse=False)[source]

Composite the ImageCollection into a single Image by picking each first-unmasked pixel.

The order of mosaicing is from last to first, meaning the last Image in the ImageCollection is on top.

Parameters

reverse (Bool, default False) – The order of mosaicing. If False (default), the last Image in the ImageCollection is on top. If True, the first `Image in the ImageCollection is on top.

Returns

mosaicked – The mosaicked Image

Return type

Image

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> col.mosaic()
<descarteslabs.workflows.types.geospatial.image.Image object at 0x...>
>>> date_mosaic = col.sorted(lambda img: img.properties['date']).mosaic()
>>> cloudfree_mosaic = col.sorted(lambda img: img.properties['cloud_fraction'], reverse=True).mosaic()
partition(i)[source]

Split this ImageCollection into two collections at index i.

If the ImageCollection is empty, a 2-tuple of empty ImageCollection objects is returned (all indices are valid).

Parameters

i (Int) – The first ImageCollection will contain all Images up to but not including index i. The second will contain the Image at index i and all subsequent ones.

Returns

Return type

Tuple[ImageCollection, ImageCollection]

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> head, tail = col.partition(1)
>>> head.compute(geoctx) 
ImageCollectionResult of length 1:
...
>>> tail.compute(geoctx) 
ImageCollectionResult of length 1:
...
pick_bands(bands, allow_missing=False)[source]

New ImageCollection, containing Images with only the given bands.

Bands can be given as a sequence of strings, or a single space-separated string (like "red green blue").

Bands on the new ImageCollection will be in the order given.

If names are duplicated, repeated names will be suffixed with _N, with N incrementing from 1 for each duplication (pick_bands("red red red") returns bands named red red_1 red_2).

If the ImageCollection is empty, returns the empty ImageCollection.

If allow_missing is False (default), raises an error if given band names that don’t exist in the ImageCollection. If allow_missing is True, any missing names are dropped, and if none of the names exist, returns an empty ImageCollection.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> rgb = col.pick_bands("red green blue")
>>> rgb.bandinfo.keys().inspect(ctx)  
["red", "green", "blue"]
>>> red = col.pick_bands(["red", "nonexistent_band_name"], allow_missing=True)
>>> red.bandinfo.keys().inspect(ctx)  
["red"]
>>> s1_col = ImageCollection.from_id("sentinel-1:GRD")
>>> vv_vh_vv = s1_col.pick_bands("vv vh vv")
>>> vv_vh_vv.bandinfo.keys().inspect(ctx)  
["vv", "vh", "vv_1"]
publish(id, version, title='', description='', public=False, labels=None, tags=None, docstring='', version_labels=None, client=None)

Publish this proxy object as a Workflow version.

Parameters
  • id (str) – ID for the new Workflow. This should be of the form "email:workflow_name" and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow.

  • version (str) – The version to be set, tied to the given proxy_object. This should adhere to the semantic versioning schema.

  • title (str, default "") – User-friendly title for the Workflow.

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • public (bool, default False) – Whether this Workflow will be publicly accessible.

  • labels (dict, optional) – Key-value pair labels to add to the Workflow.

  • tags (list, optional) – A list of strings to add as tags to the Workflow.

  • docstring (str, default "") – The docstring for this version.

  • version_labels (dict, optional) – Key-value pair labels to add to the version.

  • client (workflows.client.Client, optional) – Allows you to use a specific client instance with non-default auth and parameters

Returns

workflow – The saved Workflow object. workflow.id contains the ID of the new Workflow.

Return type

Workflow

reduce(func, initial='__NO_INITIAL_REDUCE_VALUE__')

Reduce a collection of elements to a single element.

NOTE: Optimized reducers such as sum have been implemented for some classes.

Parameters
  • func (Python callable) – A function where the left argument is the accumulated value (the result of the previous call to func) and the right argument is the next value from the iterable. The function should return a single proxtype.

  • initial (Proxytype, optional) – An optional proxtype to provide for the first iteration. If no value is provided, the first element will be used.

Returns

The return value of func for the last iteration of the collection.

Return type

Proxytype

Example

>>> from descarteslabs.workflows import List, Int
>>> def add(accumulated, current):
...     return accumulated + current
>>> my_list = List[Int]([1, 2])
>>> my_list.reduce(add, initial=Int(10)).compute()  
13
rename_bands(*new_positional_names, **new_names)[source]

New ImageCollection, with bands renamed by position or name.

New names can be given positionally (like rename_bands('new_red', 'new_green')), which renames the i-th band to the i-th argument.

Or, new names can be given by keywords (like rename_bands(red="new_red")) mapping from old band names to new ones.

To eliminate ambiguity, names cannot be given both ways.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> renamed = col.rename_bands(red="new_red", blue="new_blue", green="new_green")
replace_empty_with(fill, mask=True, bandinfo=None)[source]

Replace ImageCollection, if empty, with fill value.

Parameters
  • fill (int, float, ImageCollection) – The value to fill the ImageCollection with. If int or float, the fill value will be broadcasted to a 1 image collection, with band dimensions as determined by the geocontext and provided bandinfo.

  • mask (bool, default True) – Whether to mask the band data. If mask is True and fill is an ImageCollection, the original ImageCollection mask will be overridden and all underlying data will be masked. If mask is False and fill is an ImageCollection, the original mask is left as is. If fill is scalar, the ImageCollection constructed will be fully masked or fully un-masked data if mask is True and False respectively.

  • bandinfo (dict, default None) – Bandinfo used in constructing new ImageCollection. If fill is an ImageCollection, bandinfo is optional, and will be ignored if provided. If fill is a scalar, the bandinfo will be used to determine the number of bands on the new ImageCollection, as well as become the bandinfo for it.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> # no imagery exists for this product within the date range
>>> empty_col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-02-28")
>>> empty_col.compute(geoctx) 
ImageCollectionResult of length 0:
...
>>> non_empty = empty_col.replace_empty_with(9999, bandinfo={"red":{}, "green":{}, "blue":{}})
>>> non_empty.compute(geoctx) 
ImageCollectionResult of length 0:
  * ndarray: MaskedArray<shape=(1, 3, 512, 512), dtype=int64>
  * properties: 0 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
scale_values(range_min, range_max, domain_min=None, domain_max=None)[source]

Given an interval, band values will be scaled to the interval.

If the ImageCollection is empty, returns the empty ImageCollection.

Parameters
  • range_min (float) – Minimum value of output range.

  • range_max (float) – Maximum value of output range.

  • domain_min (float, default None) – Minimum value of the domain. If None, the band minimum is used.

  • domain_max (float, default None) – Maximum value of the domain. If None, the band maximum is used.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.compute(geoctx).ndarray 
masked_array(
  data=[[[[0.1578, 0.1578, 0.1578, ..., 0.13920000000000002, 0.1376,
                 0.1376],
...
>>> scaled = col.scale_values(0.1, 0.5).compute(geoctx) 
>>> scaled.ndarray 
masked_array(
  data=[[[[0.10000706665039064, 0.10000706665039064,
...
sin()[source]

Element-wise sine of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.sin().compute(geoctx) 
ImageCollectionResult of length 2:
...
sortby_composite(band, operation='argmax')[source]

Sort-by composite of an ImageCollection Creates a composite of an ImageCollection using the argmin or argmax of a specified band as the per-pixel ordering.

Parameters
  • band (Str or ImageCollection) – If Str, the name of the band in self to use as the sorting band. If ImageCollection, use this single-band ImageCollection as the sorting band.

  • operation ({"argmin", "argmax"}, default "argmax") – A string indicating whether to use the minimum or maximum from band when computing the sort-by composite.

Returns

composite

Return type

Image

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> rgb = col.pick_bands("red green blue")
>>> min_red_composite = rgb.sortby_composite("red", operation="argmin")
>>> # ^ compute a minimum sort-by composite with an existing band
>>> quality_band = col.pick_bands("swir1")
>>> max_swir_composite = rgb.sortby_composite(quality_band)
>>> # ^ compute a maximum sort-by composite with a provided band
sorted(key, reverse=False)[source]

Copy of this ImageCollection, sorted by a key function.

If the ImageCollection is empty, returns the empty ImageCollection.

Parameters
  • key (Function) – Function which takes an Image and returns a value to sort by.

  • reverse (Bool, default False) – Sorts in ascending order if False (default), descending if True.

Returns

sorted

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> month_reverse_sort = col.sorted(key=lambda img: img.properties["date"].month, reverse=True)
sqrt()[source]

Element-wise square root of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.sqrt().compute(geoctx) 
ImageCollectionResult of length 2:
...
square()[source]

Element-wise square of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.square().compute(geoctx) 
ImageCollectionResult of length 2:
...
std(axis=None)[source]

Standard deviation along the provided axis, or across all pixels in the image collection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the standard deviation.

Options:

  • "images": Returns an Image containing standard deviation across all scenes, for each pixel in each band (i.e., a temporal standard deviation composite.)

  • "bands": Returns a new ImageCollection with one band, "std", containing the standard deviation across all bands, for each pixel in each scene.

  • "pixels" Returns a List[Dict[Str, Float]] containing each band’s standard deviation, for each scene in the collection.

  • None: Returns a Float that represents the standard deviation of the entire ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] containing the standard deviation across all scenes, for each band, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] containing the standard deviation across all bands, for each scene.

  • ("images", "bands"): Returns an Image containing the standard deviation across all scenes and bands.

Returns

Standard deviation along the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> std_composite = col.std(axis="images")
>>> std_col = col.std(axis="bands")
>>> band_stds_per_scene = col.std(axis="pixels")
>>> scene_stds = col.std(axis=("bands", "pixels"))
>>> band_stds = col.std(axis=("images", "pixels"))
>>> std = col.std(axis=None)
sum(axis=None)[source]

Sum of pixel values across the provided axis, or across all pixels in the image collection if no axis argument is provided.

If the ImageCollection is empty, an empty (of the type determined by axis) will be returned.

Parameters

axis ({None, "images", "bands", "pixels", ("images", "pixels"), ("bands", "pixels"), ("images", "bands")}) –

A Python string indicating the axis along which to take the sum.

Options:

  • "images": Returns an Image containing the sum across all scenes for each pixel in each band (i.e., a temporal sum composite.)

  • "bands": Returns a new ImageCollection with one band, "sum", containing the sum across all bands for each pixel and each scene.

  • "pixels" Returns a List[Dict[Str, Float]] containing the sum of the pixel values for each band in each scene.

  • None: Returns a Float that represents the sum of all pixel values in the ImageCollection, across all scenes, bands, and pixels.

  • ("images", "pixels"): Returns a Dict[Str, Float] containing the sum of the pixel values for each band across all scenes, keyed by band name.

  • ("bands", "pixels"): Returns a List[Float] contianing the sum of the pixel values for each scene across all bands.

  • ("images", "bands"): Returns an Image containing the sum across all scenes and bands.

Returns

Sum of pixel values across the provided axis. See the options for the axis argument for details.

Return type

Dict[Str, Float], List[Float], List[Dict[Str, Float]], ImageCollection, Image or Float

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR")
>>> sum_composite = col.sum(axis="images")
>>> sum_col = col.sum(axis="bands")
>>> band_sums_per_scene = col.sum(axis="pixels")
>>> scene_sums = col.sum(axis=("bands", "pixels"))
>>> band_sums = col.sum(axis=("images", "pixels"))
>>> sum_pixel = col.sum(axis=None)
tail(n)[source]

ImageCollection of the last n Images.

If the ImageCollection is empty, an empty ImageCollection is returned (all values of n are valid).

Parameters

n (Int) – Can be longer than the ImageCollection without error, in which case the whole ImageCollection is returned.

Returns

imgs

Return type

ImageCollection

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.tail(1).compute(geoctx) 
ImageCollectionResult of length 1:
...
tan()[source]

Element-wise tangent of an ImageCollection.

If the ImageCollection is empty, returns the empty ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.tan().compute(geoctx) 
ImageCollectionResult of length 2:
...
unpack_bands(bands)

Convenience method for unpacking multiple bands into Python variables.

Returns a Python tuple of self.pick_bands called for each band name. Bands can be given as a space-separated string of band names, or a sequence.

Example

>>> from descarteslabs.workflows import Image
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> red, green, blue = img.unpack_bands("red green blue")
value_at(x, y)[source]

Given coordinates x, y, returns the pixel values from an ImageCollection in a List[Dict] by bandname.

Coordinates must be given in the same coordinate reference system as the GeoContext you call compute with. For example, if your GeoContext uses "EPSG:4326", you’d give x and y in lon, lat degrees. If your GeoContext uses UTM, you’d give x and y in UTM coordinates.

When using visualize to view the Image on a map, x and y must always be given in web-mercator ("EPSG:3857") coordinates (with units of meters, not degrees).

If the ImageCollection is empty, returns an empty List[Dict].

Parameters
  • x (float) – The x coordinate, in the same CRS as the GeoContext

  • y (float) – The y coordinate, in the same CRS as the GeoContext

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.compute(geoctx).ndarray 
>>> rgb = col.pick_bands("red green blue") # an Image with the red, green, and blue bands only
>>> rgb.value_at(459040.0, 3942400.0).compute(ctx) 
[{'red': 0.3569,
'green': 0.33890000000000003,
'blue': 0.37010000000000004},
{'red': 0.2373,
'green': 0.24480000000000002,
'blue': 0.2505}]
with_bandinfo(band, **bandinfo)[source]

New ImageCollection, with the given **bandinfo fields added to the specified band’s bandinfo.

If a given field already exists on the band’s bandinfo, it will be overwritten.

If the ImageCollection is empty, returns the empty ImageCollection.

Parameters
  • band (Str) – The name of the band whose bandinfo will be added to.

  • **bandinfo (dict) – Fields that will be added to the band’s bandinfo

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> with_foo = col.with_bandinfo("red", foo="baz")
>>> with_foo.bandinfo["red"]["foo"].compute(geoctx) 
'baz'
without_bandinfo(band, *bandinfo_keys)[source]

New ImageCollection, with each given *bandinfo_keys field dropped from the specified band’s bandinfo.

If a given field doesn’t exists on the band’s bandinfo, it will be a no-op.

Parameters
  • band (Str) – The name of the band whose bandinfo will be pruned.

  • *bandinfo_keys (Str) – Fields that will be dropped from the band’s bandinfo

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.bandinfo["red"].compute(geoctx) 
{'color': 'Red',
 'data_description': 'TOAR, 0-10000 is 0 - 100% reflective',
...
>>> without_desc = col.without_bandinfo("red", "data_description")
>>> without_desc.bandinfo["red"].compute(geoctx) 
{'color': 'Red',
 'data_range': [0, 10000],
...
property bandinfo

Metadata about the bands of the ImageCollection.

bandinfo is a Dict, where keys are band names and values are Dicts which always contain these fields:

  • id (Str): the Descartes Labs ID of the band

  • name (Str): the name of the band. Equal to the key the Dict is stored under in bandinfo

  • data_range (Tuple): The (min, max) values the original data had. However, data in Images is automatically rescaled to physical range, or [0, 1] if physical range is undefined, so it won’t be in data_range anymore.

Accessing other fields will return instances of Any. Accessing fields that don’t actually exist on the data is a compute-time error.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> imgs = ImageCollection.from_id("landsat:LC08:PRE:TOAR")
>>> imgs.bandinfo['red']['data_range']
<descarteslabs.workflows.types.containers.tuple_.Tuple[Float, Float] object at 0x...>
>>> imgs.bandinfo['red']['foobar']  # almost certainly a compute-time error
<descarteslabs.workflows.types.primitives.any_.Any object at 0x...>
>>> imgs.bandinfo['foobar']['id']  # also likely a compute-time error
<descarteslabs.workflows.types.primitives.string.Str object at 0x...>
Type

Dict[Str, KnownDict[dict(data_range=Tuple[Float, Float], id=Str, name=Str), Str, Any]]

property nbands

The number of bands in the ImageCollection.

If the ImageCollection is empty, returns 0.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-05-30")
>>> col.nbands.compute(geoctx) 
27
property ndarray

MaskedArray

property properties

Metadata for each Image in the ImageCollection.

properties is a List of Dict, each of which always contains these fields:

  • id (Str): the Descartes Labs ID of the Image

  • product (Str): the Descartes Labs ID of the product the Image belogs to

  • date (Datetime): the UTC date the Image was acquired

  • crs (Str): the original Coordinate Reference System of the Image

  • geotrans (Tuple): The original 6-tuple GDAL geotrans for the Image.

Accessing other fields in the Dict will return instances of Any. Accessing fields that don’t actually exist on the data is a compute-time error.

Note that you can call compute on properties as a quick way to just retrieve metadata. Since properties is a List, you can also call List.map, List.filter, etc. on it.

Example

>>> from descarteslabs.workflows import ImageCollection
>>> imgs = ImageCollection.from_id("landsat:LC08:PRE:TOAR")
>>> result = imgs.properties.compute(ctx)  
>>> type(result)  
list
>>> imgs.properties[0]['date']
<descarteslabs.workflows.types.datetimes.datetime_.Datetime object at 0x...>
>>> imgs.properties.map(lambda p: p['crs'])
<descarteslabs.workflows.types.containers.list_.List[Str] object at 0x...>
>>> imgs.properties[-1]['foobar']  # almost certainly a compute-time error
<descarteslabs.workflows.types.primitives.any_.Any object at 0x...>
Type

List[KnownDict[dict(crs=Str, date=Datetime, geotrans=Tuple[Float, Float, Float, Float, Float, Float], id=Str, product=Str), Str, Any]]

concat(*imgs)[source]

ImageCollection of imgs concatenated to one another, where imgs is a variable number of Image or ImageCollection objects.

Images and properties are concatenated. Bandinfos are intersected. All collections must have the same number of bands with identical names. Any empty Image or ImageCollection objects will not be concatenated.

Example

>>> from descarteslabs.workflows import Image, ImageCollection, concat
>>> img = Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...        start_datetime="2017-01-01",
...        end_datetime="2017-05-30")
>>> # imagery must have same bands to be concatenated
>>> rgb_img = img.pick_bands("red green blue")
>>> rgb_col = col.pick_bands("red green blue") # rgb_col has 2 images
>>> # geoctx is an arbitrary geocontext for the imagery
>>> concat(rgb_col, rgb_img).compute(geoctx) 
ImageCollectionResult of length 3:
  * ndarray: MaskedArray<shape=(3, 3, 512, 512), dtype=float64>
  * properties: 3 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
Parameters

*imgs (variable number of Image or ImageCollection objects) –

Returns

concatenated

Return type

ImageCollection

conv2d(obj, filt)[source]

2-D spatial convolution of an Image or ImageCollection.

Example

>>> from descarteslabs.workflows import Image, Kernel, conv2d
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> rgb = img.pick_bands("red green blue")
>>> kernel = Kernel(dims=(3,3), data=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0,9.0])
>>> conv2d(rgb, kernel).compute(geoctx) # geoctx is an arbitrary geocontext for 'rgb' 
ImageResult:
  * ndarray: MaskedArray<shape=(3, 512, 512), dtype=float64>
  * properties: 'acquired', 'area', 'bits_per_pixel', 'bright_fraction', ...
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
load_geojson(geojson)[source]

Create a Workflows Geometry, GeometryCollection, Feature, or FeatureCollection from a GeoJSON mapping.

Parameters

geojson (dict) – Dict-like object representing a GeoJSON Geometry, Feature, FeatureCollection.

Returns

geometry

Return type

Geometry, GeometryCollection, Feature, or FeatureCollection

Example

>>> from descarteslabs.workflows import load_geojson
>>> # type will be inferred based on the contents of the GeoJSON
>>> # geometry
>>> geojson = {"type": "Point", "coordinates": [1, 2]}
>>> load_geojson(geojson)
<descarteslabs.workflows.types.geospatial.geometry.Geometry object at 0x...>
>>> # geometry collection
>>> geojson = {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [1, 2]}]}
>>> load_geojson(geojson)
<descarteslabs.workflows.types.geospatial.geometrycollection.GeometryCollection object at 0x...>
>>> # feature
>>> geojson = {"type": "Feature",
...            "geometry": {"type": "Point", "coordinates": [1, 2]},
...            "properties": {"foo": "bar"}}
>>> load_geojson(geojson)
<descarteslabs.workflows.types.geospatial.feature.Feature object at 0x...>
>>> # feature collection
>>> geojson = {"type": "FeatureCollection",
...            "features": [{"type": "Feature",
...              "geometry": {"type": "Point", "coordinates": [1, 2]},
...              "properties": {"foo": "bar"}}]}
>>> load_geojson(geojson)
<descarteslabs.workflows.types.geospatial.featurecollection.FeatureCollection object at 0x...>
load_geojson_file(path)[source]

Create a Workflows Geometry, GeometryCollection, Feature, or FeatureCollection from a GeoJSON file.

Parameters

path (str or path-like object) –

Path to a file on disk containing GeoJSON data for a Geometry, Feature, or FeatureCollection.

Files of more than ~1MiB are not recommended. For larger amounts of data, try the Vector service and FeatureCollection.from_vector_id.

Returns

geometry

Return type

Geometry, GeometryCollection, Feature, or FeatureCollection

Example

>>> from descarteslabs.workflows import load_geojson_file
>>> # type will be inferred based on the contents of the GeoJSON in the file
>>> obj = load_geojson_file("path/to/geojson/file") 
where(condition, x, y)[source]

Returns an Image or ImageCollection with values chosen from x or y depending on condition. The bandnames of the returned imagery will be of the format <band name>_where_<condition band name> for each band in condition. Depending on the number of bands in x and y, <band name> can be taken from x, y, x_or_y, or condition.

Example

>>> from descarteslabs.workflows import Image, ImageCollection, where
>>> img = Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red")
>>> col = ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01",
...     end_datetime="2017-05-30").pick_bands("blue")
>>> # geoctx is an arbitrary geocontext for the imagery
>>> # fill pixels where col < 0.5 with col (no change), others with 0
>>> where(col < 0.5, col, 0).compute(geoctx) 
ImageCollectionResult of length 2:
  * ndarray: MaskedArray<shape=(2, 1, 512, 512), dtype=float64>
  * properties: 2 items
  * bandinfo: 'blue_where_blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
>>>
>>> # fill pixels where col < 0.5 with col (no change), others with pixels from img
>>> where(col < 0.5, col, img).compute(geoctx) 
ImageCollectionResult of length 2:
  * ndarray: MaskedArray<shape=(2, 1, 512, 512), dtype=float64>
  * properties: 2 items
  * bandinfo: 'red_or_blue_where_red'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...
Parameters
Returns

An Image or ImageCollection with values from x where condition is True, and values from y elsewhere.

Return type

Image, ImageCollection