Note

Using interactive maps requires ipyleaflet, an optional dependency. See the guide for installation and troubleshooting instructions.

Interactive

Classes

WorkflowsLayer(image, *args, **kwargs)

Subclass of ipyleaflet.TileLayer for displaying a Workflows Image.

LayerController(map, **kwargs)

An ipyleaflet.WidgetControl for managing WorkflowsLayer.

LayerControllerList(map)

Widget displaying a list of LayerControllerRow widgets for a Map.

Map(**kwargs)

Subclass of ipyleaflet.Map with Workflows defaults and extra helper methods.

MapApp([map, layer_controller_list, …])

Widget displaying a map, layers, and output logs in a nicer layout.

ParameterSet(notify_object, notify_name, …)

Parameters for a WorkflowsLayer, which updates the layer when new values are assigned.

ProxytypeInstance([klass, args, kw])

Trait type that tries to promote values to a given Proxytype

Data

map

A single MapApp instance that all visualize calls are automatically added to.

class WorkflowsLayer(image, *args, **kwargs)[source]

Subclass of ipyleaflet.TileLayer for displaying a Workflows Image.

Attributes

attribution

A trait for unicode strings.

autoscale_progress

A trait whose value must be an instance of a specified class.

b_max

Casting Float traitlet that also considers the empty string as None

b_min

Casting Float traitlet that also considers the empty string as None

checkerboard

A boolean (True, False) trait.

cmap_max

Casting Float traitlet that also considers the empty string as None

cmap_min

Casting Float traitlet that also considers the empty string as None

colormap

A trait for unicode strings.

error_output

A trait whose value must be an instance of a specified class.

g_max

Casting Float traitlet that also considers the empty string as None

g_min

Casting Float traitlet that also considers the empty string as None

image

A trait whose value must be an instance of a specified class.

min_zoom

An int trait.

parameters

A trait whose value must be an instance of a specified class.

r_max

Casting Float traitlet that also considers the empty string as None

r_min

Casting Float traitlet that also considers the empty string as None

session_id

A trait for unicode strings.

url

A trait for unicode strings.

xyz_obj

A trait whose value must be an instance of a specified class.

Methods

forget_errors()

Clear the set of known errors, so they are re-displayed if they occur again

make_url()

Generate the URL for this layer.

set_parameters(**params)

Set new parameters for this WorkflowsLayer.

set_scales(scales[, new_colormap])

Update the scales for this layer by giving a list of scales

image

The Image to use

Type

Image

parameters

Parameters to use while computing; modify attributes under .parameters (like layer.parameters.foo = "bar") to cause the layer to recompute and update under those new parameters.

Type

ParameterSet

xyz_obj

Read-only: The XYZ object this layer is displaying.

Type

XYZ

session_id

Read-only: Unique ID that error logs will be stored under, generated automatically.

Type

str

checkerboard

Whether to display a checkerboarded background for missing or masked data.

Type

bool, default True

colormap

Name of the colormap to use. If set, image must have 1 band.

Type

str, optional, default None

cmap_min

Min value for scaling the single band when a colormap is given.

Type

float, optional, default None

cmap_max

Max value for scaling the single band when a colormap is given.

Type

float, optional, default None

r_min

Min value for scaling the red band.

Type

float, optional, default None

r_max

Max value for scaling the red band.

Type

float, optional, default None

g_min

Min value for scaling the green band.

Type

float, optional, default None

g_max

Max value for scaling the green band.

Type

float, optional, default None

b_min

Min value for scaling the blue band.

Type

float, optional, default None

b_max

Max value for scaling the blue band.

Type

float, optional, default None

error_output

If set, write unique errors from tiles computation to this output area from a background thread. Setting to None stops the listener thread.

Type

ipywidgets.Output, optional, default None

Public constructor

forget_errors()[source]

Clear the set of known errors, so they are re-displayed if they occur again

make_url()[source]

Generate the URL for this layer.

This is called automatically as the attributes (image, colormap, scales, etc.) are changed.

set_parameters(**params)[source]

Set new parameters for this WorkflowsLayer.

In typical cases, you update parameters by assigning to parameters (like layer.parameters.threshold = 6.6).

Instead, use this function when you need to change the names or types of parameters available on the WorkflowsLayer. (Users shouldn’t need to do this, as visualize handles it for you, but custom widget developers may need to use this method when they change the image field on a WorkflowsLayer.)

If a value is an ipywidgets Widget, it will be linked to that parameter (via its "value" attribute). If a parameter was previously set with a widget, and a different widget instance (or non-widget) is passed for its new value, the old widget is automatically unlinked. If the same widget instance is passed as is already linked, no change occurs.

Parameters

params (JSON-serializable value, Proxytype, or ipywidgets.Widget) – Paramter names to new values. Values can be Python types, Proxytype instances, or ipywidgets.Widget instances.

set_scales(scales, new_colormap=False)[source]

Update the scales for this layer by giving a list of scales

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

  • new_colormap (str, None, or False, optional, default False) – A new colormap to set at the same time, or False to use the current colormap.

attribution

A trait for unicode strings.

autoscale_progress

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

b_max

Casting Float traitlet that also considers the empty string as None

b_min

Casting Float traitlet that also considers the empty string as None

checkerboard

A boolean (True, False) trait.

cmap_max

Casting Float traitlet that also considers the empty string as None

cmap_min

Casting Float traitlet that also considers the empty string as None

colormap

A trait for unicode strings.

error_output

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

g_max

Casting Float traitlet that also considers the empty string as None

g_min

Casting Float traitlet that also considers the empty string as None

image

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

min_zoom

An int trait.

parameters

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

r_max

Casting Float traitlet that also considers the empty string as None

r_min

Casting Float traitlet that also considers the empty string as None

session_id

A trait for unicode strings.

url

A trait for unicode strings.

xyz_obj

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

class LayerController(map, **kwargs)[source]

An ipyleaflet.WidgetControl for managing WorkflowsLayer.

Unlike other ipyleaflet controls, a Map must be passed in on instantiation. Creating a LayerController automatically adds it to the given Map.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("landsat:LC08:PRE:TOAR:meta_LC80270312016188_v1").pick_bands("red green blue")
>>> map = wf.Map()  
>>> layer = wf.WorkflowsLayer(img)  
>>> map.add_layer(layer)  
>>> ctl = wf.LayerController(map)  
>>> map  
controller_list

The LayerControllerList widget displayed.

Type

LayerControllerList

Create the LayerController.

Parameters

map (Map) – The Map to which to add this control.

class LayerControllerList(map)[source]

Widget displaying a list of LayerControllerRow widgets for a Map.

Public constructor

Attributes

map

A trait whose value must be an instance of a specified class.

map

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

class Map(**kwargs)[source]

Subclass of ipyleaflet.Map with Workflows defaults and extra helper methods.

Attributes

autoscale_outputs

A trait whose value must be an instance of a specified class.

center

An instance of a Python list.

error_log

A trait whose value must be an instance of a specified class.

min_zoom

An int trait.

output_log

A trait whose value must be an instance of a specified class.

scroll_wheel_zoom

A boolean (True, False) trait.

zoom_start

An int trait.

Methods

geocontext()

A Workflows GeoContext representing the current view area and resolution of the map.

move_layer(layer, new_index)

Move a layer to a new index.

move_layer_down(layer)

Move a layer down one, if not already at the bottom.

move_layer_up(layer)

Move a layer up one, if not already at the top.

output_log

Widget where functions doing operations on this map (especially compute operations, like autoscaling or timeseries) can log their output.

Type

ipywidgets.Output

Public constructor

geocontext()[source]

A Workflows GeoContext representing the current view area and resolution of the map.

Returns

geoctx

Return type

GeoContext

move_layer(layer, new_index)[source]

Move a layer to a new index.

Parameters
  • layer (ipyleaflet.Layer) –

  • new_index (int) –

:raises ValueError:: If layer is a base layer, or does not already exist on the map.

move_layer_down(layer)[source]

Move a layer down one, if not already at the bottom.

Parameters

layer (ipyleaflet.Layer) –

:raises ValueError:: If layer is a base layer, or does not already exist on the map.

move_layer_up(layer)[source]

Move a layer up one, if not already at the top.

Parameters

layer (ipyleaflet.Layer) –

:raises ValueError:: If layer is a base layer, or does not already exist on the map.

autoscale_outputs

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

center

An instance of a Python list.

error_log

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

min_zoom

An int trait.

output_log

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

scroll_wheel_zoom

A boolean (True, False) trait.

zoom_start

An int trait.

class MapApp(map=None, layer_controller_list=None, position_controller=None)[source]

Widget displaying a map, layers, and output logs in a nicer layout.

Forwards attributes and methods to self.map.

Public constructor

Methods

clear_layers()

Remove all layers from the map (besides the base layer)

remove_layer(layer_name)

Remove a named layer from the map

clear_layers()[source]

Remove all layers from the map (besides the base layer)

remove_layer(layer_name)[source]

Remove a named layer from the map

class ParameterSet(notify_object, notify_name, **traits)[source]

Parameters for a WorkflowsLayer, which updates the layer when new values are assigned.

A ParameterSet is constructed automatically when calling Image.visualize and added to the WorkflowsLayer; you shouldn’t construct one manually.

You can access a widget for interactively controlling these parameters at widget.

Methods

add_traits(**traits)

Dynamically add trait attributes to the HasTraits instance.

link(name, target[, attr])

Link an attribute to an ipywidget (or other object).

make_widget([skip])

Make a widget for controlling these parameters.

remove_traits(*names)

Remove traits that were dynamically added to the HasTraits instance

to_dict()

Key-value pairs of the parameters.

update(**new_values)

Update the ParameterSet with a dict of new values.

widget

A widget showing a table of controls, linked to this ParameterSet. Updating the controls causes the map to update.

Type

ipywidgets.Widget

Example

>>> import descarteslabs.workflows as wf
>>> imgs = wf.ImageCollection.from_id(
...     "sentinel-1:GRD", start_datetime=wf.parameter("start", wf.Datetime)
... )
>>> filtered = imgs.filter(lambda img: img.properties['pass'] == wf.parameter("pass_dir", wf.Str))
>>> composite = imgs.mean(axis="images").pick_bands("vv")
>>> lyr = composite.visualize("vv mean", start=wf.Datetime(2018), pass_dir="ASCENDING")  
>>> params = lyr.parameters  
>>> # ^ get the ParameterSet for the layer
>>> params.pass_dir  
"ASCENDING"
>>> params.pass_dir = "DESCENDING"  
>>> # ^ this updates the layer on the map
>>> params.start = "2019-01-01"  
>>> # ^ as does this
>>> params.link("start", my_ipywidget)  
>>> # ^ this links the "start" parameter to an ipywidget's value

Notes

The names and types of fields on a ParameterSet are fixed, and can only be changed using update. This means that on a ParameterSet that only has the field x, which holds a float, params.x = "foo" will fail (wrong type), as will params.y = "bar" (y doesn’t exist).

When Image.visualize creates a ParameterSet for you, it adds fields for whichever parameter names you give at the time. For example, img.visualize("my layer", foo="bar", baz=100) will create the fields foo and bar. More importantly, it infers the type of those fields from the values passed, so foo would only accept strings, and bar would only accept ints.

Therefore, if you experience a TypeError assiging to a ParameterSet field, you may need to change the initial value passed into the Image.visualize call, so that the correct type is inferred.

You shouldn’t need to construct a ParameterSet manually, but here’s how you would:

Parameters
  • notify_object (traitlets.HasTraits instance) – The object to notify when any of the traits on this ParameterSet change

  • notify_name (str) – The name to use in the change notification sent to that object

  • **traits (traitlets.TraitType instances) – The traits to add to this ParameterSet

add_traits(**traits)[source]

Dynamically add trait attributes to the HasTraits instance.

Link an attribute to an ipywidget (or other object).

If a link to the attribute was previously created, it is unlinked.

Parameters
  • name (str) – The name of the parameter to link

  • target (ipywidgets.Widget, any traitlets.HasTraits instance, or None) – The object to link to. If None, any existing link to name is removed.

  • attr (str, default "value") – The name of the attribute on target to link to. Defaults to "value", since that works for most ipywidgets.

make_widget(skip=None)[source]

Make a widget for controlling these parameters.

Widgets that were passed in or linked are displayed. For values that aren’t already linked to a widget, an appropriate widget type is chosen if possible.

Note that this widget can become out of date and unlinked once update is called; use the widget property for an always-up-to-date widget.

Parameters

skip (list[str]) – Sequence of parameter names to not include in the widget

Returns

widget – A widget showing a table of controls, linked to this ParameterSet. Updating the widgets causes the map to update. If there are no parameters to display, returns None.

Return type

ipywidgets.Widget or None

remove_traits(*names)[source]

Remove traits that were dynamically added to the HasTraits instance

to_dict()[source]

Key-value pairs of the parameters.

update(**new_values)[source]

Update the ParameterSet with a dict of new values.

New parameters are added as fields on the ParameterSet, with their trait type inferred from the value.

Current parameters that are not present in new_values are removed from the ParameterSet.

Passing a value of a different type to a current parameter will change its trait type.

If a value is an ipywidgets Widget, it will be linked (via its "value" attribute) to that parameter. If a parameter was previously linked to a widget, and a different widget instance (or non-widget) is passed for its new value, the old widget is automatically unlinked. If the same widget instance is passed as is already linked, no change occurs.

Parameters

**new_values (JSON-serializable value, Proxytype, or ipywidgets.Widget) – Parameter names to new values. Values can be Python types, Proxytype instances, or ipywidgets.Widget instances.

class ProxytypeInstance(klass=None, args=None, kw=None, **kwargs)[source]

Trait type that tries to promote values to a given Proxytype

Construct an Instance trait.

This trait allows values that are instances of a particular class or its subclasses. Our implementation is quite different from that of enthough.traits as we don’t allow instances to be used for klass and we handle the args and kw arguments differently.

Parameters
  • klass (class, str) – The class that forms the basis for the trait. Class names can also be specified as strings, like ‘foo.bar.Bar’.

  • args (tuple) – Positional arguments for generating the default value.

  • kw (dict) – Keyword arguments for generating the default value.

  • allow_none (bool [ default False ]) – Indicates whether None is allowed as a value.

Methods

validate(obj, value)

Notes

If both args and kw are None, then the default value is None. If args is a tuple and kw is a dict, then the default is created as klass(*args, **kw). If exactly one of args or kw is None, the None is replaced by () or {}, respectively.

validate(obj, value)[source]
map = `ipyleaflet` and/or `ipywidgets` Jupyter extensions are not installed! (or you're not in a Jupyter notebook.) To install for JupyterLab, run this in a cell: !jupyter labextension install jupyter-leaflet @jupyter-widgets/jupyterlab-manager To install for plain Jupyter Notebook, run this in a cell: !jupyter nbextension enable --py --sys-prefix ipyleaflet Then, restart Jupyter and re-run this notebook.

A single MapApp instance that all visualize calls are automatically added to.

Run:

wf.map

in a JupyterLab cell to display the map the first time, then right-click and select “New View for Output”. You can then position and rearrange the map as a tab however you like.

Calling Image.visualize will by default add new layers to this map.