Geospatial

Classes

Kernel(**kwargs)

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

Feature(**kwargs)

FeatureCollection(features)

Construct a FeatureCollection from a sequence of Features

GeoContext(**kwargs)

Geometry(**kwargs)

GeometryCollection(**kwargs)

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

Functions

conv2d(obj, filt)

2-D spatial convolution of 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.

class Kernel(**kwargs)[source]

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

Methods

compute([geoctx, timeout, block, …])

Compute this proxy object and wait for its result.

publish([name, description, client])

Publish this proxy object as a Workflow.

Attributes

data

List containing the kernel data in row-major format

dims

Tuple containing the dimensions of the kernel

compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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(**kwargs)[source]

Methods

buffer(distance)

compute([geoctx, timeout, block, …])

Compute this proxy object and wait for its result.

from_geojson(geojson)

publish([name, description, client])

Publish this proxy object as a Workflow.

rasterize([value, default_value])

Rasterize this Feature into an Image

Attributes

geometry

Geometry

properties

Dict[Str, Any]

buffer(distance)
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

classmethod from_geojson(geojson)[source]
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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

property geometry

Geometry

property properties

Dict[Str, Any]

class FeatureCollection(features)[source]

Construct a FeatureCollection from a sequence of Features

Methods

compute([geoctx, timeout, block, …])

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)

from_vector_id(id)

length()

Length is equivalent to the Python len operator.

map(func)

Map a function over an iterable proxytype.

publish([name, description, client])

Publish this proxy object as a Workflow.

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 collection, sorted by a key function.

Attributes

features

List[Feature]

compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

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

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

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

Length is equivalent to the Python len operator.

Returns

An Int Proxytype

Return type

Int

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

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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

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

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

Copy of this collection, sorted by a key function.

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

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

property features

List[Feature]

class GeoContext(**kwargs)[source]

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.

Methods

compute([geoctx, timeout, block, …])

Compute this proxy object and wait for its result.

from_dltile_key(key)

from_scenes(ctx)

Construct a Workflows GeoContext from a Scenes GeoContext

from_xyz_tile(x, y, z)

publish([name, description, client])

Publish this proxy object as a Workflow.

compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

classmethod from_dltile_key(key)[source]
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]
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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

class Geometry(**kwargs)[source]

Methods

buffer(distance)

compute([geoctx, timeout, block, …])

Compute this proxy object and wait for its result.

from_geo_interface(obj)

from_geojson(geojson)

publish([name, description, client])

Publish this proxy object as a Workflow.

rasterize([value])

Rasterize this Geometry into an Image

Attributes

coordinates

List[Any]

type

Str

buffer(distance)
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

classmethod from_geo_interface(obj)[source]
classmethod from_geojson(geojson)[source]
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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)[source]

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

property coordinates

List[Any]

property type

Str

class GeometryCollection(**kwargs)[source]

Methods

buffer(distance)

compute([geoctx, timeout, block, …])

Compute this proxy object and wait for its result.

from_geo_interface(obj)

from_geojson(geojson)

publish([name, description, client])

Publish this proxy object as a Workflow.

rasterize([value])

Rasterize this Geometry into an Image

Attributes

coordinates

List[Any]

geometries

List[Geometry]

type

Str

buffer(distance)
compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

classmethod from_geo_interface(obj)
classmethod from_geojson(geojson)[source]
publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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

property coordinates

List[Any]

property geometries

List[Geometry]

property type

Str

class ImageCollectionGroupby(imgs, func)[source]

Dict-like object for a grouped ImageCollection.

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

Parameters
Returns

grouped

Return type

ImageCollectionGroupby

Methods

compute(*args, **kwargs)

Compute this proxy object and wait for its result.

count([axis])

Apply ImageCollection.count to each group

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

one()

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

publish([name, description, client])

Publish this proxy object as a Workflow.

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

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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

count(axis=None)[source]

Apply ImageCollection.count to each group

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.)

max(axis=None)[source]

Apply ImageCollection.max to each group

mean(axis=None)[source]

Apply ImageCollection.mean to each group

median(axis=None)[source]

Apply ImageCollection.median to each group

min(axis=None)[source]

Apply ImageCollection.min to each group

one()[source]

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

publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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

sum(axis=None)[source]

Apply ImageCollection.sum to each group

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.

Attributes

bandinfo

Metadata about the bands of the Image.

properties

Metadata for the Image.

Methods

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, timeout, block, …])

Compute this proxy object and wait for its result.

concat_bands(other_image)

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

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.

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'

log()

Element-wise natural log of an Image

log10()

Element-wise base 10 log of 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)

New Image, containing only the given bands.

publish([name, description, client])

Publish this proxy object as a Workflow.

rename_bands(*new_positional_names, **new_names)

New Image, with bands renamed by position or name.

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

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.

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

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

clip_values(min=None, max=None)[source]

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

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.) –

colormap(named_colormap='viridis', vmin=None, vmax=None)[source]

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

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.) –

compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

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”.

cos()[source]

Element-wise cosine of an Image

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.

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)
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, cubicsplice, 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

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'

log()[source]

Element-wise natural log of an Image

log10()[source]

Element-wise base 10 log of an Image

log2()[source]

Element-wise base 2 log of an Image

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.

mask(mask, replace=False)[source]

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

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.

max(axis=None)[source]

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

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.

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.

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.

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)

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.

publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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.

scale_values(range_min, range_max, domain_min=None, domain_max=None)[source]

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

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.

sin()[source]

Element-wise sine of an Image

sqrt()[source]

Element-wise square root of an Image

std(axis=None)[source]

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

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.

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

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.

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

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> red, green, blue = img.unpack_bands("red green blue")
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.

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

>>> import descarteslabs.workflows as wf
>>> img = wf.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 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

>>> import descarteslabs.workflows as wf
>>> img = wf.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

Construct an ImageCollection from a sequence of Images

Attributes

bandinfo

Metadata about the bands of the ImageCollection.

properties

Metadata for each Image in the ImageCollection.

Methods

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, timeout, block, …])

Compute this proxy object and wait for its result.

concat(*imgs)

New ImageCollection with imgs concatenated to this one, where imgs is a variable number of ImageCollection objects.

concat_bands(other)

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

contains(other)

Contains is equivalient to the Python in operator.

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.

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

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

log2()

Element-wise base 2 log of an ImageCollection

map(func)

Map a function over an iterable proxytype.

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.

partition(i)

Split this ImageCollection into two collections at index i.

pick_bands(bands)

New ImageCollection, containing Images with only the given bands.

publish([name, description, client])

Publish this proxy object as a Workflow.

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.

scale_values(range_min, range_max[, …])

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

sin()

Element-wise sine of an ImageCollection

sorted([key, reverse])

Copy of this collection, sorted by a key function.

sqrt()

Element-wise square root 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.

clip_values(min=None, max=None)[source]

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

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.) –

colormap(named_colormap='viridis', vmin=None, vmax=None)[source]

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

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.) –

compute(geoctx=None, timeout=None, block=True, progress_bar=None, channel=None, client=None, **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.

  • timeout (int, optional) – The number of seconds to wait for the result, if block is True. Raises TimeoutError 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.

  • channel (str or None, optional) –

    Channel name to submit the Job to. If None, uses the default channel for this client (descarteslabs.workflows.__channel__).

    Channels are different versions of the backend, to allow for feature changes without breaking existing code. Not all clients are compatible with all channels. This client is only guaranteed to work with its default channel, whose name can be found under descarteslabs.workflows.__channel__.

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

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

Returns

Appropriate Python object representing the result, either as a plain Python type, or object from descarteslabs.workflows.results.

Return type

result

concat(*imgs)[source]

New ImageCollection with imgs concatenated to this one, where imgs is a variable number of ImageCollection objects.

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

Parameters

*imgs (variable number of ImageCollection objects) –

Returns

concatenated

Return type

ImageCollection

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”.

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

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

cos()[source]

Element-wise cosine of an ImageCollection

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.

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)
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

>>> import descarteslabs.workflows as wf
>>> col = wf.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.

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, cubicsplice, 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

imgs

Return type

ImageCollection

getmask()[source]

Mask of this ImageCollection, as a new ImageCollection with one boolean band named ‘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]

head(n)[source]

ImageCollection of the first n Images

Parameters

n (Int) – Can be longer than the ImageCollection without error, in which case the whole ImageCollection is returned.

Returns

imgs

Return type

ImageCollection

length()

Length is equivalent to the Python len operator.

Returns

An Int Proxytype

Return type

Int

log()[source]

Element-wise natural log of an ImageCollection

log10()[source]

Element-wise base 10 log of an ImageCollection

log2()[source]

Element-wise base 2 log of an ImageCollection

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

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("sentinel-2:L1C")
>>> dates = col.map(lambda img: img.properties["date"])
>>> type(dates).__name__
'List[Datetime]'
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.

Parameters

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

Returns

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.

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

mask(mask, replace=False)[source]

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

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.

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.

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.

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.

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.

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)
partition(i)[source]

Split this ImageCollection into two collections at index i.

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]

pick_bands(bands)[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 Images will be in the order given.

publish(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

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

  • 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

>>> import descarteslabs.workflows as wf
>>> def add(accumulated, current):
...     return accumulated + current
>>> l = wf.List[wf.Int]([1, 2])
>>> reduced = l.reduce(add, initial=wf.Int(10))
>>> reduced.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.

scale_values(range_min, range_max, domain_min=None, domain_max=None)[source]

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

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.

sin()[source]

Element-wise sine of an ImageCollection

sorted(key=None, reverse=False)

Copy of this collection, sorted by a key function.

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

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

sqrt()[source]

Element-wise square root of an ImageCollection

std(axis=None)[source]

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

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.

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

Parameters

n (Int) – Can be longer than the ImageCollection without error, in which case the whole ImageCollection is returned.

Returns

imgs

Return type

ImageCollection

tan()[source]

Element-wise tangent of an ImageCollection

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

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> red, green, blue = img.unpack_bands("red green blue")
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

>>> import descarteslabs.workflows as wf
>>> imgs = wf.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 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

>>> import descarteslabs.workflows as wf
>>> imgs = wf.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]]

conv2d(obj, filt)[source]

2-D spatial convolution of Image or ImageCollection.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1")
>>> rgb = img.pick_bands(["red", "green", "blue"])
>>> w = wf.Kernel(dims=(3,3), data=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0,9.0])
>>> t = wf.conv2d(rgb, w)
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

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

where(condition, x, y)[source]

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

Parameters
Returns

An Image or ImageCollection with values from x where condition is True, and values from y elsewhere.

Return type

Image, ImageCollection