WMTS

Workflows implements Open Geospatial Consortium’s (OGC) Web Map Tile Server (WMTS) specification for visualization of Workflows layers in desktop GIS software. Client applications that support OGC WMTS services, such as ArcGIS Pro and QGIS, will be able to render published Workflows Images that are computed on-demand.

Overview

Published Workflows Images can be visualized in tools that support OGC WMTS connections.

A WMTS Service URL will prompt the user for their username and token before retrieving the list of available published Workflows for visualization. This URL remains static and relies on a user’s authentication with the Platform to retrieve the list of available layers and to fetch the imagery.

Publishing Workflows for WMTS

Supported Workflows Types

Workflows Image and Workflows ImageCollection are supported for use with WMTS.

Setting Visualization Parameters

When users publish Workflows for use with WMTS, they can specify one or more Workflows VizOption to indicate how a layer should appear once rendered. These Visualization Options have the following parameters:

  • id (str) – Name of the Visualization Option instance to help users differentiate between options.
  • bands (str or list) – List of band names to render. Can be a list of band names, or a string of space separated band names. This parameter allows a user to choose multiple band combinations for different Visualization Options.
  • checkerboard (bool, default False) – Whether or not to render a checkerboard pattern in place of empty pixels.
  • colormap (str, optional) – Name of colormap to use if the image has a single band.
  • reduction (str, default “mosaic”.) – Name of reduction operation if the published Workflow is an ImageCollection. Defaults to mosaic, other options are median, mean, min, max, std, and count.
  • scales (list, optional) – Scales to use when rendering the layer. Must be the same length as the number of bands.
  • description (str, optional) – Description of the Visualization Option.

Example

Given a Sentinel 2 ImageCollection with red, green, blue, and near-infrared bands, users may want to visualize those as red-green-blue or nir-red-green. The following example shows how to create these options.

>>> s2 = (
    wf.ImageCollection.from_id('sentinel-2:L1C', start_datetime='2020-06-01', end_datetime='2020-09-01')
    .pick_bands('red green blue nir')
)
>>> rgb_option = wf.VizOption(
    'RGB Mosaic',
    bands='red green blue',
    scales=[[0.,0.4],[0.,0.4],[0.,0.4]]
)
>>> nrg_option = wf.VizOption(
    'NRG Median',
    bands='nir red green',
    reduction='median',
    scales=[[0.,0.4],[0.,0.4],[0.,0.4]]
)

Publishing

Once Visualization Options have been defined, users can publish the Workflow with those options. Publishing is a way to save and version your Workflow such that it can be used later by referencing its name.

Example

Continuing from the above example, users can publish the s2 ImageCollection with two predefined Visualization Options. For more information on publishing Workflows, see publish.

>>> my_workflow = s2.publish(
    'me@company.com:sentinel_2',
    '0.0.2',
    title='Sentinel 2 - Summer 2020',
    description='Sentinel 2 imagery from summer of 2020',
    viz_options=[rgb_option, nrg_option]
)

Generating a WMTS URL

Users can publish a set of Workflows and retrieve a WMTS Service URL that can be used to access all Workflows readable by the user, an individual Workflow, or a single version of an individual Workflow. Users can read Workflows they have created or those that have been shared with them. For more information see Sharing.

Each WMTS URL will provide access to published Workflows compatible with the user’s current Workflows channel. For instance, a Workflow published using channel v0-17 will not be accessible through a WMTS URL generated by a user on v0-18.

All readable Workflows: wf.wmts_url() Produces a URL similar to the following: https://workflows.prod.descarteslabs.com/v0-18/wmts/workflow/1.0.0/WMTSCapabilities.xml

Individual Workflow: my_workflow.wmts_url() Produces a URL similar to the following: https://workflows.prod.descarteslabs.com/v0-18/wmts/workflow/me@company.com:sentinel_2/1.0.0/WMTSCapabilities.xml

Specific version of an individual Workflow: my_workflow.versions[-1].wmts_url() Produces a URL similar to the following: https://workflows.prod.descarteslabs.com/v0-18/wmts/workflow/me@company.com:sentinel_2/0.0.2/1.0.0/WMTSCapabilities.xml

Authentication & Access

WMTS Service URLs provide access to published Workflows and must be authenticated using the user’s credentials. Specifically, the user’s email address and JSON Web Token (JWT) are used to authenticate the user with the Descartes Labs Platform.

Note

Note that JWTs expire after 10 hours, after which point a new JWT needs to be generated and entered into the WMTS client.

Using WMTS in GIS Software

Each Visualization Option for a given published Workflow version can be visualized as a layer in a GIS tool. Using the WMTS URLs shown above, users can configure the list of Workflows returned when the connection is made between the GIS tool and the Descartes Labs Platform.

There are three common fields needed to access Workflows layers using WMTS:

  • URL: Depending on the type of WMTS URL you intend to add, you should use one of the following
  • Username (Required for WMTS Service URL): This should be set to the email address used for your Descartes Labs account
  • Password (Required for WMTS Service URL): This is a JSON Web Token (JWT) and should be retrieved from this Credentials page

Supported Applications

Application Support Level Notes
ArcGIS Pro Full Support
Quantum GIS (QGIS) Full Support

ArcGIS Pro

Navigate to Insert > Connections > New WMTS Server

Paste the WMTS URL in the Server URL field. If using a WMTS Service URL, fill in the username and password fields with the email attached to your Descartes Labs account and a JWT retrieved from this link. Click OK.

In the Catalog pane, you will now see a Server connection titled Descartes Labs Workflows Web Map Tile Service. Expanding two levels will show you the list of layers published.

Add a layer to the map by right clicking > Add to Current Map

By default, the map may zoom out to view the entire world. We recommend turning the layer off in this case and zooming back in to your region of interest.

QGIS

Navigate to Layer > Data Source Manager > WMS/WMTS or Layer > Add Layer > Add WMS/WMTS Layer

Then, click New under the Layers menu in the top menu bar and fill out the Name and URL for the connection. If using a WMTS Service URL, click Basic within the Authentication section and enter the email used for your Descartes Labs account and your token retrieved from this Credentials page.

Ensure the new connection is selected in the dropdown, and click Connect to bring up the list of layers, which will appear in the Tilesets tab. or, your connection will now appear under WMTS/WMTS in the Browser interface.

Select the appropriate visualization configuration and right-click > Add Layer to Project.

Differences in Client WMTS Implementations

Although OGC’s WMTS specification has been successfully implemented by a number of client applications (e.g. ArcGIS, QGIS, and others), there are differences in the user experience when using each of these.