An on-demand geospatial compute engine.

Dynamic Compute

Dynamic-Compute is a map computation engine. It enables users to dynamically generate maps from a composable set of Python operations. Together, these properties enable data scientists in the building of complex GIS applications.

The Dynamic Compute API can be found as Python package descarteslabs.dynamic-compute.

class Mosaic(graft, bands=None, product_id=None, start_datetime=None, end_datetime=None)

Class wrapper around mosaic operations

argmax(axis)

Apply np.ma.argmax to the ComputeMap

Parameters:: axis – (str) Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”]. If called on an ImageStack, must be in [“bands”, “images”]
Returns:: Mosaic

clip(lo, hi)

Generate a new Mosaic that is bounded by low and hi.

Parameters:

lo (Number) – Lower bound
hi (Number) – Upper bound

Returns:

bounded – New Mosaic object that is bounded

Return type:

Mosaic

compute(aoi)

Evaluate this ComputeMap for a particular AOI

Parameters:: aoi (descarteslabs.geo.GeoContext) – GeoContext for which to compute evaluate this ComputeMap
Returns:: results – Evaluation of self for this AOI. The return will be either an array, properties as a list, properties as dict, or both as a DotDict
Return type:: Union[Array, List, Dict, DotDict]

concat_bands(other)

Create a new Mosaic that stacks bands. This call does not mutate this

Parameters:: other (Union[Mosaic, str]) – concat the bands of this mosiac with those of other, if other is a Mosaic. otherwise assume other is a list of bands and concat this with those bands.
Returns:: stack – Mosaic object with stacked bands
Return type:: Mosaic

classmethod from_product_bands(product_id, bands, start_datetime=None, end_datetime=None, **kwargs)

Create a new Mosaic object

Parameters:

product_id (str) – ID of the product from which we want to access data
bands (Union[str, List[str]]) – A space-separated list of bands within the product, or a list of strings.
start_datetime (Optional[Union[str, datetime.date, datetime.datetime]) – Start date for mosaic
end_datetime (Optional[Union[str, datetime.date, datetime.datetime]) – End date for mosaic

Returns:

m – New mosaic object.

Return type:

Mosaic

mask(mask)

Apply a mask as a delayed object. This call does not mutate this

Parameters:: mask (ComputeMap) – Delayed object to use as a mask.
Returns:: masked – Masked mosaic.
Return type:: Mosaic

max(axis)

Apply np.ma.max to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

mean(axis)

Apply np.ma.mean to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

median(axis)

Apply np.ma.median to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

min(axis)

Apply np.ma.min to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

pick_bands(bands)

Create a new Mosaic object with the specified bands and the product-id of this Mosaic object

Parameters:: bands (str) – A space-separated list of bands within the product, or a list of bands as strings
Returns:: m – New mosaic object.
Return type:: Mosaic

reduce(reducer, axis='bands')

Call a reduction function on this Mosaic

Parameters:

reducer (Callable) – function to reduce Mosaic
axis (str) – Axis over which to call the reducer, must be in [“bands”].

Raises:

NotImplementedError – axis must be bands

Returns:

Mosaic

rename_bands(bands): Rename the bands of an array.

std(axis)

Apply np.ma.std to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

sum(axis)

Apply np.ma.sum to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

tile_layer(name=None, scales=None, colormap=None, checkerboard=True, log_level=10, **parameter_overrides)

A .DynamicComputeLayer for this Mosaic.

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

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

Parameters:

name (str) – The name of the layer.
scales (list of lists, default None) –
The scaling to apply to each band in the Mosaic.

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

If Mosaic 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 Mosaic. Only valid if the Mosaic has a single band.
checkerboard (bool, default True) – Whether to display a checkerboarded background for missing or masked data.
log_level (int, default logging.DEBUG) – Only listen for log records at or above this log level during tile computation. See https://docs.python.org/3/library/logging.html#logging-levels for valid log levels.
**parameter_overrides (JSON-serializable value, Proxytype, or ipywidgets.Widget) –
Values—or ipywidgets—for any parameters that this Mosaic depends on.

If this Mosaic depends on dc.widgets, you don’t have to pass anything for those—any widgets it depends on are automatically linked to the layer. However, you can override their current values (or widgets) by passing new values (or ipywidget instances) here.

Values can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.

If an ipywidgets.Widget is given, it’s automatically linked, so updating the widget causes the argument value to change, and the layer to update.

Once these initial argument values are set, they can be modified by assigning to ~.DynamicComputeLayer.parameters on the returned DynamicComputeLayer.

For more information, see the docstring to ParameterSet.

Returns:

layer

Return type:

.DynamicComputeLayer

unpack_bands(bands)

Create a tuple of new Mosaic objects with one for each bands.

Parameters:: bands (str) – A space-separated list of bands within the product.
Returns:: m – New mosaic object per band passed in.
Return type:: Tuple[Mosaic, …]

visualize(name, map, colormap=None, scales=None, checkerboard=True, **parameter_overrides)

Visualize this Mosaic instance on a map. This call does not mutate this :param name: Name of this layer on the map :type name: str :param map: IPyleaflet map on which to add this mosaic as a layer :type map: ipyleaflet.leaflet.Map :param colormap: Optional colormap to use :type colormap: str :param scales: List of lists of lower and upper bounds, length equal to number of bands :type scales: list :param checkerboard: Whether to display a checkerboarded background for missing or masked data :type checkerboard: bool

Returns:: layer – IPyleaflet tile layer on the map.
Return type:: lyr

class ImageStack(full_graft, scenes_graft=None, bands=None, product_id=None, start_datetime=None, end_datetime=None)

argmax(axis)

Apply np.ma.argmax to the ComputeMap

Parameters:: axis – (str) Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”]. If called on an ImageStack, must be in [“bands”, “images”]
Returns:: Mosaic

compute(aoi)

Evaluate this ComputeMap for a particular AOI

Parameters:: aoi (descarteslabs.geo.GeoContext) – GeoContext for which to compute evaluate this ComputeMap
Returns:: results – Evaluation of self for this AOI. The return will be either an array, properties as a list, properties as dict, or both as a DotDict
Return type:: Union[Array, List, Dict, DotDict]

concat_bands(other)

Create a new ImageStack that stacks bands. This call does not mutate this

Note that per-image metadata for the returned ImageStack instance is taken from self not other.

Parameters:: other (ImageStack) – concat the bands of this ImageStack with those of other
Returns:: stack – ImageStack object with stacked bands
Return type:: ImageStack

filter(f)

Filter an image stack to based on image properties.

Parameters:: f (Callable[[dl.catalog.Image], bool]) – Filter function. This function must take a dl.catalog.Image object and return a bool indicating that the image should be retained (True) or excluded (False)
Returns:: New ImageStack object.
Return type:: ImageStack

classmethod from_product_bands(product_id, bands, start_datetime, end_datetime, **kwargs)

Create a new ImageStack object

Parameters:

product_id (str) – ID of the product from which we want to access data
bands (Union[str, List[str]]) – A space-separated list of bands within the product, or a list of strings.
start_datetime (Union[str, datetime.date, datetime.datetime]) – Start date for image stack
end_datetime (Union[str, datetime.date, datetime.datetime]) – End date for image stack

Returns:

m – New ImageStack object.

Return type:

ImageStack

groupby(grouping_func)

Perform a grouping function over either images or bands and return an ImageStackGroupBy object.

Parameters:: grouping_func (Callable[[np.ndarray], np.ndarray]) – Function to pick out the values to group by
Returns:
Return type:: ImageStackGroupBy object.

Example

>>> import descarteslabs.dynamic_compute as dc 
>>> m = dc.map 
>>> m 
>>> sigma0_vv = dc.ImageStack.from_product_bands( 
        "esa:sentinel-1:sigma0v:v1", "vv", "20230101", "20230401" 
    ) 
>>> # group by acquired month
>>> grouped_sigma = sigma0_vv.groupby(lambda x: x.acquired.month) 
>>> # loop through each grouping, applying a max reducer and visualize it on the map
>>> for group_name, image_stack in grouped_sigma.compute(m.geocontext()): 
        image_stack.max(axis="images").visualize(str(group_name), m, colormap="turbo") 

length()

Proxy object for the length of this image stack

Returns:: compute_map – Proxy object for the length
Return type:: ComputeMap

mask(mask)

Apply a mask as a delayed object. This call does not mutate this

Parameters:: mask (ComputeMap) – Delayed object to use as a mask.
Returns:: masked – Masked mosaic.
Return type:: Mosaic

max(axis)

Apply np.ma.max to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

mean(axis)

Apply np.ma.mean to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

median(axis)

Apply np.ma.median to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

min(axis)

Apply np.ma.min to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

pick_bands(bands)

Create a new ImageStack object with the specified bands and the product-id of this ImageStack object

Parameters:: bands (str) – A space-separated list of bands within the product, or a list of bands as strings
Returns:: m – New mosaic object.
Return type:: ImageStack

reduce(reducer, axis='images')

Perform a reduction over either images or bands. Note that this does not mutate self.

Parameters:

reducer (Callable[[np.ndarray], np.ndarray]) – Function to perform the reduction
axis (str) – Axis over which to reduce, either “bands” or “images”

Returns:

new_obj – Reduced object, either a Mosaic if axis is “images” or an ImageStack if axis is “bands”

Return type:

Union[Mosaic, ImageStack]

rename_bands(bands): Rename the bands of an array.

std(axis)

Apply np.ma.std to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

sum(axis)

Apply np.ma.sum to the ComputeMap

Parameters:: axis (str) – Axis over which to call the reducer. If called on a Mosaic, must be in [“bands”].
Returns:: ComputeMap

unpack_bands(bands)

Create a tuple of new ImageStack objects with one for each bands.

Parameters:: bands (str) – A space-separated list of bands within the product.
Returns:: m – New mosaic object per band passed in.
Return type:: Tuple[ImageStack, …]