Interactive Maps in Jupyter

Some Workflows objects can be viewed on an interactive map in a Jupyter Notebook. Rather than calling .compute() with an explicit GeoContext, the workflow is computed on-the-fly for the area you’re viewing in the map.

Using Workbench

The fastest and easiset way to get started with interactive maps is to use the Descartes Labs Workbench. There is no installation required, simply log in and create a new Jupyter Notebook. See Usage for instructions on how to use wf.map.

Local Installation

To use the interactive map locally, you will need an installation of either JupyterLab (recommended) or Jupyter Notebook. Installation instructions for both can be found here. Additionally, the map requires ipyleaflet, which is included when running pip install --upgrade "descarteslabs[complete]", or by manually running pip install ipyleaflet.

Currently, ipyleaflet requires some additional installation steps to make widgets show up in Jupyter. For JupyterLab:

jupyter labextension install jupyter-leaflet @jupyter-widgets/jupyterlab-manager

If you’re using plain Jupyter Notebook and maps don’t show up, try:

jupyter nbextension enable --py --sys-prefix ipyleaflet

See Usage for instructions on how to use wf.map.

Usage

wf.map is a single MapApp instance that all layers are added to by default. To use the map, one of your first cells should be:

import descarteslabs.workflows as wf
wf.map

This will display the map below that cell. Right-clicking on the map and selecting ‘New View for Output’, will allow you to rearrange the map as its own tab.

Then, calling visualize will add a new layer to wf.map. (Note that visualize just adds the layer; nothing will show up directly underneath that cell.) Using the provided layer controls, you can adjust scaling, set colormaps for single-band images, perform autoscaling to the current viewport with the “Autoscale” button, and rearrange layers.

Currently, only Image objects can be displayed. To visualize an ImageCollection, first composite it (using mean, min, etc.) into an Image. To visualize vector data, you can rasterize it into an Image.

Troubleshooting

• Running wf.map shows “A Jupyter widget could not be displayed because the widget state could not be found.”:

  The ipyleaflet Jupyter plugins aren’t installed correctly. Make sure the ipyleaflet Python package is installed in your environment, and follow the installation steps above.

• You call Image.visualize(), but nothing shows up on the map:

  Sometimes it just takes a while. However, you can try the following steps to verify your environment is correct.

  1. Make sure you’re logged in to your Descartes Labs account. Visit iam.descarteslabs.com, log in, then refresh the Jupyter page.
  2. Verify that you have the latest version of the descarteslabs client installed. You can print descarteslabs.__version__, or open a terminal and run pip freeze | grep descarteslabs. To upgrade your client to the latest version run pip install --upgrade "descarteslabs[complete]". The most recent version of the client is listed on PyPI.
  3. Make sure that the layer visibility is on. This is indicated with a small checkbox at the far left of the layer row under the map. Additionally, the slider to the right of the checkbox controls opacity, with the right-most position indicating 100% opacity.
  4. If the layer visibility and opacity are turned on and you still see nothing, check that the checkerboard button is turned on for the layer, or pass checkerboard=True to visualize. If you see a checkerboard pattern on the map, this means that your job returned empty imagery for that area, which may mean you are viewing the wrong area or could indicate an issue with your code.
  
  5. Check status.descarteslabs.com for updates about currently ongoing outages.

If you’re still having trouble, please contact support@descarteslabs.com.