Exploring an ItemCollection

Let’s load an ItemCollection of Landsat 8 scenes from the Planetary Computer STAC and preview them with stacmap.explore.

[1]:

import stacmap
import pystac_client

[2]:

catalog = pystac_client.Client.open("https://planetarycomputer.microsoft.com/api/stac/v1")

aoi = {"type": "Polygon", "coordinates": [[
    [-112.2068359375, 42.41050500280784],
    [-112.2068359375, 39.25270077697571],
    [-107.9880859375, 39.25270077697571],
    [-107.9880859375, 42.41050500280784],
    [-112.2068359375, 42.41050500280784]
]]}

items = catalog.search(
    collections=["landsat-8-c2-l2"],
    intersects=aoi,
    datetime="2019-06-01/2019-06-10"
).get_all_items()

Calling stacmap.explore with a STAC Collection* will preview the item footprints on an interactive map. Hover over each footprint to see its STAC metadata.

*Currently supported STAC-like types are: pystac.Catalog, pystac.ItemCollection, pystac.Item, collection dictionaries, item dictionaries, and lists of item dictionaries.

[5]:

stacmap.explore(items)

[5]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Color-Coding

Footprints can be color-coded based on STAC properties using the prop parameter. The default colormap can be replaced with any colorbrewer name using cmap. Additional color maps are supported if matplotlib is installed.

Continuous Properties

By default, numeric properties are colored continuously and given continuous legends. Color map bounds are calculated automatically, but can be overriden by providing vmin and vmax arguments.

[15]:

stacmap.explore(items, prop="view:sun_elevation", cmap="Reds")

[15]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Categorical Properties

Non-numeric properties are treated categorically by default, with a color assigned to each unique value. You can force a numerical field to plot categorically using categorical=True.

[13]:

stacmap.explore(items, prop="proj:epsg", categorical=True)

[13]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Search Extents

Pass a bounding box to bbox or a GeoJSON geometry to intersects to overlay your search bounds.

[14]:

stacmap.explore(items, prop="landsat:wrs_path", intersects=aoi)

[14]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Custom Styling

Visualization styles can be customized using style_kwds, highlight_kwds, and bounds_kwds. stacmap.explore follows the geopandas.GeoDataFrame.explore implementation for these styling options, so check out their docs to get a list of supported options. You can also customize the Folium basemap using the tiles parameter.

[12]:

stacmap.explore(
    items, tiles="CartoDB dark_matter", intersects=aoi,
    style_kwds={"color": "#c44500", "weight": 4, "fillOpacity": 0.1},
    highlight_kwds={"fillOpacity": 0.9},
    bounds_kwds={"color": "#ffe814", "opacity": 1.0}
)

[12]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Custom Metadata

Filtering Properties

By default, stacmap.explore gives a tooltip that displays the item ID and all STAC properties on-hover. Metadata properties can be filtered by passing a list of properties to include to fields or by passing one or more STAC extension prefixes to extensions. Note that with the second option, base STAC properties are always included.

[21]:

stacmap.explore(items, extensions=["view", "eo"])

[21]:

Make this Notebook Trusted to load map: File -> Trust Notebook

More Metadata Options

Swap on-hover tooltips for on-click popups with tooltip=False, popup=True.
Set shared_props=True to only include properties that are shared by all items. Otherwise, if items contain different properties then missing properties will be filled with None.
Avoid automatically adding each item’s STAC ID to the metadata properties with add_id=False.

Using Existing Maps

stacmap.explore returns a Folium map. You can add multiple STAC collections by passing an existing map to the m parameter. Pass a name parameter with each STAC collection to allow layer control. Below, we’ll split the Landsat items into two sub-groups and plot each separately on the same map.

[26]:

m = stacmap.explore(items[:5], name="Landsat #1", prop="proj:epsg", categorical=True)
stacmap.explore(items[5:], m=m, name="Landsat #2", prop="eo:cloud_cover", cmap="BrBG", fields=["eo:cloud_cover", "instruments"])
m

[26]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Thumbnails

Some STAC items have links to thumbnail assets. If they are available, you can overlay thumbnail images by setting thumbnails=True. Note that catalogs like Planetary Computer may need to be signed to access thumbnails.

[10]:

import planetary_computer

stacmap.explore(planetary_computer.sign(items[0]), thumbnails=True, style_kwds={"fill": False})

[10]:

Make this Notebook Trusted to load map: File -> Trust Notebook

Note

This page was auto-generated from a Jupyter notebook. For full functionality, download the notebook from Github and run it in a local Python environment.